Debug a Cloud Run service in Cloud Code for Cloud Shell
Stay organized with collections
Save and categorize content based on your preferences.
Cloud Code for Cloud Shell lets you easily debug an application deployed to
Cloud Run by leveraging
skaffold debug. For detailed
information about Skaffold debugging, see
Debugging with Skaffold.
You don't need to complete manual setup like setting up port forwarding or
injecting language-specific debug arguments. Debugging requires a
Cloud Code-ready Cloud Run application
that includes a skaffold.yaml configuration file and a launch.json file of
type cloudcode.cloudrun.
Debug your Cloud Run service
To debug your service, follow these steps:
To run your service and attach a debugger session to it, open the
command palette (press Ctrl/Cmd+Shift+P or click View >
Command Palette)
and then run the Debug on Cloud Run Emulator command.
In the Run/Debug on Cloud Run Emulator dialog, set the
specifications for your configuration:
Choose Docker or Buildpacks as your builder and then specify your
Dockerfile or Buildpack.
(Optional) To specify a Dockerfile target or build arguments,
click Show Advanced Build Settings and then specify the target or
arguments.
(Optional) To specify a custom service name, container image URL,
container port, identity for the service to use, number of dedicated CPUs,
or amount of memory to allocate to each container instance, click
Show Advanced Service Settings and then specify the values.
(Optional) To specify any
environment variables,
click Show Advanced Service Settings, click Environment Variables,
and then specify the values.
(Optional) To specify Cloud SQL connections, click Connections
and then specify one connection per line.
If you want to further customize how your service is run, you can edit
your launch.json file
directly.
To begin debugging your service, click Debug.
For each debuggable container in your service, confirm or enter the directory
in the remote container where the program you'd like to debug is found.
Alternatively, you can press ESC to skip debugging a container.
Cloud Code attaches a debug session for each debuggable
container in the service.
By default, when a change to your application is autosaved,
Cloud Code redeploys your application and sets up a new debug
session. You can toggle this feature with the watch flag in your project's
launch configuration.
To add a breakpoint, click in the editor margin of the file you're debugging.
Red filled circles signify active breakpoints and gray hollow circles
signify disabled breakpoints.
When you send a new request to your service, it pauses at the line you
specified.
After your session completes, right-click to use the following commands:
View Logs: Open the application logs of a specific
deployment with the Cloud Code Logs Explorer
Open URL: Open the application service URL of a specific
service in a web browser
If you've turned off watch mode in your launch configuration and you want to
make changes to your application and rebuild and redeploy the application,
click the Cloud Code status bar and then click
Turn on watch mode.
If you want to inspect variables and stack info, use the
Debug Sidebar.
To interact with the debugging session, use the
Debug Console
in the bottom pane debugger.
To stop your deployment, click the Stop button in the action bar for your
current deployment.
Troubleshoot container-building issues
If you're getting the BUILD_DOCKER_UNKNOWN error code, this indicates a
problem with Docker. To resolve this issue, perform one or more of the following
tasks:
Restart Docker and try building the container again.
If you're still getting the same error after restarting, Docker could be
running out of disk space. To learn more about cleaning up unused objects in
Docker, see Prune unused Docker objects.
Try Docker's Disk Usage
extension to help reclaim space.
Configuration details
Cloud Code handles the following language-specific configuration
details:
Node.js
Rewriting the entrypoint to invoke:
node --inspect=localhost:9229
Python
Installing the ptvsd module using an Init Container and rewriting the
entrypoint to invoke:
python -m ptvsd --host localhost --port 5678
Go
Installing the
dlv debugger
using an Init Container and rewriting the entrypoint such that the launched
debug session runs with a debug server only (in headless mode), continues the
debugged process on start, accepts multiple client connections, and listens at
localhost:56268:
Adding an environment JAVA_TOOLS_OPTIONS with the appropriate Java Debug
Wire Protocol (JDWP) configuration such that the JDWP debugging agent listens
for a socket connection on port 5005 and allows the VM to begin executing
before the debugger is attached:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-07 UTC."],[[["\u003cp\u003eCloud Code for Cloud Shell simplifies debugging Cloud Run applications by utilizing \u003ccode\u003eskaffold debug\u003c/code\u003e, eliminating the need for manual port forwarding or language-specific debug argument setups.\u003c/p\u003e\n"],["\u003cp\u003eDebugging a Cloud Run service involves using the "Debug on Cloud Run Emulator" command, configuring build and service settings, and then initiating the debug process.\u003c/p\u003e\n"],["\u003cp\u003eCloud Code automatically redeploys the application and establishes a new debug session whenever changes are autosaved, which can be toggled via the 'watch' flag.\u003c/p\u003e\n"],["\u003cp\u003eCloud Code manages language-specific debugging configurations, such as entry point rewrites and debugger installations, for Node.js, Python, Go, Java, and .NET Core applications.\u003c/p\u003e\n"],["\u003cp\u003eIf you get the 'BUILD_DOCKER_UNKNOWN' error, it is an issue with Docker that can be solved by restarting docker, pruning unused objects, or by using the disk usage extension.\u003c/p\u003e\n"]]],[],null,["# Debug a Cloud Run service in Cloud Code for Cloud Shell\n\nCloud Code for Cloud Shell lets you easily debug an application deployed to\nCloud Run by leveraging\n[`skaffold debug`](https://skaffold.dev/docs/workflows/debug). For detailed\ninformation about Skaffold debugging, see\n[Debugging with Skaffold](https://skaffold.dev/docs/workflows/debug/).\n\nYou don't need to complete manual setup like setting up port forwarding or\ninjecting language-specific debug arguments. Debugging requires a\nCloud Code-ready Cloud Run application\nthat includes a `skaffold.yaml` configuration file and a `launch.json` file of\ntype `cloudcode.cloudrun`.\n\nDebug your Cloud Run service\n----------------------------\n\nTo debug your service, follow these steps:\n\n1. To run your service and attach a debugger session to it, open the\n command palette (press `Ctrl`/`Cmd`+`Shift`+`P` or click **View** \\\u003e\n **Command Palette** )\n and then run the **Debug on Cloud Run Emulator** command.\n\n2. In the Run/Debug on Cloud Run Emulator dialog, set the\n specifications for your configuration:\n\n - Choose Docker or Buildpacks as your builder and then specify your Dockerfile or Buildpack.\n - (Optional) To specify a Dockerfile target or build arguments, click **Show Advanced Build Settings** and then specify the target or arguments.\n - (Optional) To specify a custom service name, container image URL, container port, identity for the service to use, number of dedicated CPUs, or amount of memory to allocate to each container instance, click **Show Advanced Service Settings** and then specify the values.\n - (Optional) To specify any [environment variables](/code/docs/shell/develop-service#optional_customizing_your_configuration), click **Show Advanced Service Settings** , click **Environment Variables**, and then specify the values.\n - (Optional) To specify Cloud SQL connections, click **Connections** and then specify one connection per line.\n\n If you want to further customize how your service is run, you can edit\n [your `launch.json` file](/code/docs/shell/develop-service#customizing_an_existing_launchjson_configuration)\n directly.\n3. To begin debugging your service, click **Debug**.\n\n4. For each debuggable container in your service, confirm or enter the directory\n in the remote container where the program you'd like to debug is found.\n\n Alternatively, you can press `ESC` to skip debugging a container.\n\n Cloud Code attaches a debug session for each debuggable\n container in the service.\n\n\n By default, when a change to your application is autosaved,\n Cloud Code redeploys your application and sets up a new debug\n session. You can toggle this feature with the `watch` flag in your project's\n launch configuration.\n5. To add a breakpoint, click in the editor margin of the file you're debugging.\n\n Red filled circles signify active breakpoints and gray hollow circles\n signify disabled breakpoints.\n\n When you send a new request to your service, it pauses at the line you\n specified.\n6. After your session completes, right-click to use the following commands:\n\n - **View Logs:** Open the application logs of a specific deployment with the Cloud Code Logs Explorer\n - **Open URL:** Open the application service URL of a specific service in a web browser\n7. If you've turned off watch mode in your launch configuration and you want to\n make changes to your application and rebuild and redeploy the application,\n click the Cloud Code status bar and then click\n **Turn on watch mode**.\n\n8. If you want to inspect variables and stack info, use the\n [Debug Sidebar](https://code.visualstudio.com/Docs/editor/debugging).\n To interact with the debugging session, use the\n [Debug Console](https://code.visualstudio.com/Docs/editor/debugging#_debug-console-repl)\n in the bottom pane debugger.\n\n9. To stop your deployment, click the **Stop** button in the action bar for your\n current deployment.\n\n### Troubleshoot container-building issues\n\nIf you're getting the `BUILD_DOCKER_UNKNOWN` error code, this indicates a\nproblem with Docker. To resolve this issue, perform one or more of the following\ntasks:\n\n- Restart Docker and try building the container again.\n\n- If you're still getting the same error after restarting, Docker could be\n running out of disk space. To learn more about cleaning up unused objects in\n Docker, see [Prune unused Docker objects](https://docs.docker.com/config/pruning/#prune-unused-docker-objects).\n\n- Try Docker's [Disk Usage](https://hub.docker.com/extensions/docker/disk-usage-extension)\n extension to help reclaim space.\n\nConfiguration details\n---------------------\n\nCloud Code handles the following language-specific configuration\ndetails: \n\n### Node.js\n\nRewriting the entrypoint to invoke:\n\n`node --inspect=localhost:9229`\n\n### Python\n\nInstalling the `ptvsd` module using an Init Container and rewriting the\nentrypoint to invoke:\n\n`python -m ptvsd --host localhost --port 5678`\n\n### Go\n\nInstalling the\n[`dlv` debugger](https://github.com/go-delve/delve/blob/master/Documentation/usage/dlv.md)\nusing an Init Container and rewriting the entrypoint such that the launched\ndebug session runs with a debug server only (in headless mode), continues the\ndebugged process on start, accepts multiple client connections, and listens at\n`localhost:56268`:\n\n`dlv exec --headless --continue --accept-multiclient --listen=localhost:56268 --api-version=2, \u003capp\u003e --`\n\n### Java\n\nAdding an environment `JAVA_TOOLS_OPTIONS` with the appropriate Java Debug\nWire Protocol (JDWP) configuration such that the JDWP debugging agent listens\nfor a socket connection on port 5005 and allows the VM to begin executing\nbefore the debugger is attached:\n\n`jdwp=transport=dt_socket,server=y,suspend=n,address=5005,quiet=y`\n\n### .NET\n\n.NET Core applications are configured to be deployed along with `vsdbg` for VS\nCode.\n\nIf you encounter problems with the automatic configuration, see\n[Detailed debugger configuration and setup](https://skaffold.dev/docs/workflows/debug/#detailed-debugger-configuration-and-setup)\nfor help troubleshooting."]]
