Run and debug an App Engine Standard app locally in Cloud Code for IntelliJ
Prior to deploying your application to
App Engine, you can run and debug
your App Engine standard application locally. This document describes
how to configure the IDE for local run and debug from within IntelliJ IDEA.
Before you begin
Ensure your application is an App Engine standard project that
contains an appengine-web.xml file
If you're using IntelliJ IDEA Ultimate Edition, you can run an
App Engine application locally by following these instructions:
Select File > Open to open the project you want to run.
Browse to the directory containing your project.
Select Tools > Cloud Code > App EngineRun on a local
App Engine Standard dev server.
The project takes a moment to build.
Editing the run configuration
Configure the server
You can edit the run configuration for your local server:
Select Run > Edit Configurations.
From the Run/Debug Configurations dialog, update configuration settings
as needed. Some common settings include:
Artifact to deploy.
App Engine Host.
App Engine Port.
Add environment variables
If needed, add environment variables to your configuration.
Select the Startup/Connection tab.
Select Run.
Select the Pass environment variables checkbox.
Add the necessary variables.
Select Debug.
Select the Pass environment variables checkbox.
Add the necessary variables.
When finished, click OK.
Stopping the server
To stop the Dev App Server, choose Run >
Stop 'Google App Engine Standard Local Server'.
Debugging the application
You can use the run configuration you previously created to run your application
in debug mode as follows:
Select Run > Debug.
In the dialog, click Google App Engine Standard Local Server.
After the project builds, you can set breakpoints to debug your app.
Debugging your application locally on Community Edition
IntelliJ Community Edition does not provide built-in support for running local
Java servlet-based applications. To debug your application locally using IntelliJ
Community Edition, configure your project to use the
Maven or
Gradle plugin.
To submit feedback or report an issue in your IntelliJ IDE, go to
Tools > Cloud Code > Help / About > Submit
feedback or report an issue to report an issue on GitHub.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-07 UTC."],[[["\u003cp\u003eCloud Code supports running and debugging App Engine standard applications locally within IntelliJ IDEA, but Java 8 is the only supported runtime.\u003c/p\u003e\n"],["\u003cp\u003eApp Engine support in Cloud Code is being deprecated, with Java 8 support having ended in January 2024 and full deprecation scheduled for January 2026, so it's not recommended to create new App Engine projects.\u003c/p\u003e\n"],["\u003cp\u003eIntelliJ IDEA Ultimate Edition allows for direct local running and debugging through built-in configurations, while Community Edition requires using Maven or Gradle plugins.\u003c/p\u003e\n"],["\u003cp\u003eWhen debugging, you can set breakpoints and configure environment variables in the run configuration, and stopping the server is done through the Run menu.\u003c/p\u003e\n"],["\u003cp\u003eMaven or Gradle projects require the respective plugins to be added and run/debug configurations to be made for the plugin and remote debugging, for local debugging in the Community Edition of IntelliJ.\u003c/p\u003e\n"]]],[],null,["# Run and debug an App Engine Standard app locally in Cloud Code for IntelliJ\n\n| **Caution:** As of January 31, 2024, Java 8 support for App Engine has ended, and will be deprecated on January 31, 2026. As a result, Cloud Code disables App Engine by default. To enable App Engine in your IDE, navigate to **Settings** \\\u003e **Google\n| Cloud Code** \\\u003e **App Engine** . Due to the upcoming deprecation of App Engine, we don't recommend creating new App Engine projects. For more information about App Engine deprecations, see [Feature deprecations](/appengine/docs/standard/deprecations). For more information about the runtime support schedule for App Engine, see [Runtime support schedule](/appengine/docs/standard/lifecycle/support-schedule).\n\nPrior to deploying your application to\n[App Engine](/appengine/docs/standard/java), you can run and debug\nyour App Engine standard application locally. This document describes\nhow to configure the IDE for local run and debug from within IntelliJ IDEA.\n| **Note:** The following IDEs support this feature:\n|\n| - IntelliJ IDEA - Ultimate\n| - IntelliJ IDEA - Community\n| **Note:** For the App Engine standard environment, only Java applications using [Java 8 runtime](/appengine/docs/standard/java/runtime) are supported on Cloud Code.\n\nBefore you begin\n----------------\n\n- Ensure your application is an App Engine standard project that\n contains an `appengine-web.xml` file\n\n- To access the Cloud Client Libraries locally, complete the\n [Adding Cloud Client Libraries to Your Maven\n Projects](/code/docs/intellij/client-libraries) procedures.\n\n| **Note:** Run configurations for local run and debug are only available in IntelliJ Ultimate Edition. If you are using Community Edition, you can follow the [debugging your application locally on Community Edition](#community) instructions to use the Maven or Gradle plugins for your local run.\n\nRunning your application locally\n--------------------------------\n\nIf you're using IntelliJ IDEA Ultimate Edition, you can run an\nApp Engine application locally by following these instructions:\n\n1. Select **File** \\\u003e **Open** to open the project you want to run.\n\n2. Browse to the directory containing your project.\n\n3. Select **Tools** \\\u003e **Cloud Code** \\\u003e **App Engine** **Run on a local\n App Engine Standard dev server**.\n\nThe project takes a moment to build.\n\nEditing the run configuration\n-----------------------------\n\n### Configure the server\n\nYou can edit the run configuration for your local server:\n\n1. Select **Run** \\\u003e **Edit Configurations**.\n\n2. From the **Run/Debug Configurations** dialog, update configuration settings\n as needed. Some common settings include:\n\n - Artifact to deploy.\n - App Engine Host.\n - App Engine Port.\n\n### Add environment variables\n\nIf needed, add environment variables to your configuration.\n\n1. Select the **Startup/Connection** tab.\n\n2. Select **Run**.\n\n3. Select the **Pass environment variables** checkbox.\n\n4. Add the necessary variables.\n\n5. Select **Debug**.\n\n6. Select the **Pass environment variables** checkbox.\n\n7. Add the necessary variables.\n\n8. When finished, click **OK**.\n\nStopping the server\n-------------------\n\nTo stop the Dev App Server, choose **Run** \\\u003e\n**Stop 'Google App Engine Standard Local Server'**.\n\nDebugging the application\n-------------------------\n\nYou can use the run configuration you previously created to run your application\nin debug mode as follows:\n\n1. Select **Run** \\\u003e **Debug**.\n\n2. In the dialog, click **Google App Engine Standard Local Server**.\n\n3. After the project builds, you can set breakpoints to debug your app.\n\nDebugging your application locally on Community Edition\n-------------------------------------------------------\n\nIntelliJ Community Edition does not provide built-in support for running local\nJava servlet-based applications. To debug your application locally using IntelliJ\nCommunity Edition, configure your project to use the\n[Maven](/appengine/docs/standard/java/using-maven) or\n[Gradle](/appengine/docs/standard/java/using-gradle) plugin. \n\n### Maven\n\nConfiguring your project using the Maven plugin\n\n1. [Add the App Engine Maven\n plugin](/appengine/docs/standard/java/using-maven#adding_the_app_engine_maven_plugin_to_an_existing_project)\n to your project's `pom.xml` file.\n\n2. [Configure debugging on a development\n server](/appengine/docs/standard/java/using-maven#testing_your_application_with_the_development_server).\n\n3. Create Run/Debug configuration for Maven.\n\n 1. Select **Run** \\\u003e **Edit Configurations**.\n\n 2. Click **+ Add New Configuration**.\n\n 3. Select **Maven**.\n\n 4. In the **Command line** field, enter `appengine:run`.\n\n 5. Click **OK**.\n\n4. Create a remote debug configuration.\n\n 1. Select **Run** \\\u003e **Edit Configurations**.\n\n 2. Click **+ Add New Configuration**.\n\n 3. Select **Remote**.\n\n 4. Ensure that the port number is the same as the port you configured in\n your Maven App Engine plugin configuration. Port **5005** is\n the default.\n\n 5. In the **Before launch** section, click **+ Add**.\n\n 6. Select **Run Another Configuration**.\n\n 7. Select the run configuration for your Maven project.\n\n 8. Click **OK**.\n\n5. To debug your application locally:\n\n 1. Select **Run** \\\u003e **Debug**.\n\n 2. Select your remote debug configuration.\n\n You can now debug your application locally.\n\n### Gradle\n\nConfiguring your project using the Gradle plugin\n\n1. [Create a new Gradle\n project](/appengine/docs/standard/java/using-gradle#creating_a_new_project).\n\n2. [Configure debugging on a development\n server](/appengine/docs/standard/java/using-gradle#testing_gradle_app).\n\n3. Create Run/Debug configuration for Gradle.\n\n 1. Select **Run** \\\u003e **Edit Configurations**.\n\n 2. Click **+ Add New Configuration**.\n\n 3. Select **Gradle**.\n\n 4. In the **Gradle project** field, select the module where you\n configured the `appengine-gradle-plugin` plugin.\n\n 5. In the **Tasks** field, enter `appengineRun`.\n\n 6. Click **OK**.\n\n4. Create a remote debug configuration.\n\n 1. Select **Run** \\\u003e **Edit Configurations**.\n\n 2. Click **+ Add New Configuration**.\n\n 3. Select **Remote**.\n\n 4. Ensure that the port number is the same as the port you configured in\n your Gradle App Engine plugin configuration. Port **5005** is the\n default.\n\n 5. In the **Before launch** section, click **+ Add**.\n\n 6. Select **Run Another Configuration**.\n\n 7. Select the run configuration for your Gradle project.\n\n 8. Click **OK**.\n\n5. To debug your application locally:\n\n 1. Select **Run** \\\u003e **Debug**.\n\n 2. Select your remote debug configuration.\n\n You can now debug your application locally.\n 3. If the **Attach Debugger** link appears in the console log, click the\n link.\n\n | **Note:** If the port you've chosen is blocked, configure a different port number (for example, **5009**) in your Gradle App Engine plugin configuration and update the port number in the remote configuration to the same port number.\n\nWhat's next\n-----------\n\n- Next, you can deploy your app to the [App Engine standard\n environment](/code/docs/intellij/deploy-std).\n\nGet support\n-----------\n\nTo submit feedback or report an issue in your IntelliJ IDE, go to **Tools** \\\u003e **Cloud Code** \\\u003e **Help / About** \\\u003e **Submit\nfeedback or report an issue** to report an issue on [GitHub](https://github.com/GoogleCloudPlatform/cloud-code-intellij/issues)."]]
