Debug mode and logs

Enable debug mode and collect logs for CARTO Self-Hosted

Debug mode in CARTO allows you to gather additional information for troubleshooting and diagnosing issues.

Enable debug mode

Kots

Kots

To enable debug mode, enable the Debug Mode option in the configuration of your CARTO Self-Hosted platform through the Admin Console.

Helm

Helm

Update your customizations.yaml file and apply the changes:

CARTO SH Version 2025.1.10 or newer

appConfigValues:
  logLevel: "debug"

CARTO Self-Hosted version 2024.12.10 or older

importApi:
  extraEnvVars:
    - name: CARTO_TRACING_MODE
      value: "local"

importWorker:
  extraEnvVars:
    - name: CARTO_TRACING_MODE
      value: "local"

ldsApi:
  extraEnvVars:
    - name: CARTO_TRACING_MODE
      value: "local"

mapsApi:
  extraEnvVars:
    - name: CARTO_TRACING_MODE
      value: "local"

workspaceApi:
  extraEnvVars:
    - name: CARTO_TRACING_MODE
      value: "local"

workspaceSubscriber:
  extraEnvVars:
    - name: CARTO_TRACING_MODE
      value: "local"

Debug mode only takes effect once the change is deployed. See Apply configuration changes (Save config and Deploy in the Admin Console, or helm upgrade for Helm). It only affects logs written after the deploy, so if you're gathering information for Support, reproduce the issue once the deploy has finished. See Get debug information for support.

Collecting logs

To collect logs from your CARTO Self-Hosted deployment:

Kots (Single VM)

1. Open a terminal.

2. Navigate to your CARTO Self-Hosted installation directory.

3. Run the following command to start a shell with permissions to check the logs:

   ./carto shell

4. Check the logs of each container:

   kubectl logs -f <service_name> -n kotsadm

Kots (Kubernetes)

1. Open a terminal or use your preferred Kubernetes management tool.

2. Check the logs of each container:

   kubectl logs -f <service_name> -n <namespace>

Helm

Helm

1. Open a terminal or use your preferred Kubernetes management tool.

2. Check the logs of each container:

   kubectl logs -f <service_name> -n <namespace>