Troubleshooting FAQ

How do I see debug logs from CLI commands?

Add --log-level=debug to the command to see debug logs from the CLI.

How do I see the output in JSON or YAML format instead of the table format that is shown by default?

Use --out=json or --out=yaml to see the output in the corresponding format instead of JSON.

How do I output the version of the DDN CLI?

Run ddn version to see the CLI version.

Why does my engine container crash upon running ddn run docker-start during local development?

The engine Docker container can crash due to various reasons:

1. The mandatory environment variables required to configure the engine were not provided.
2. The metadata files required by the engine are invalid or non-existent.
3. The engine version is not up to date to handle new metadata objects.

1. The mandatory environment variables required to configure the engine were not provided

Error output

error: the following required arguments were not provided:
--metadata-path <PATH>
--authn-config-path <PATH>

Usage: engine --metadata-path <PATH> --authn-config-path < PATH>

For more information, try '--help'

In this case, verify that the env vars AUTHN_CONFIG_PATH, INTROSPECTION_METADATA_FILE and METADATA_PATH are passed to the engine container.

The default docker compose file generated by the CLI passes these values to the engine container:

AUTHN_CONFIG_PATH: /md/auth_config.json
ENABLE_CORS: "true"
INTROSPECTION_METADATA_FILE: /md/metadata.json
METADATA_PATH: /md/open_dd.json
OTLP_ENDPOINT: http://local.hasura.dev:4317

AUTHN_CONFIG_PATH, INTROSPECTION_METADATA_FILE and the METADATA_PATH are the paths to the files created as a result of ddn supergraph build local. These paths should be configured based on where it is mounted in the engine container.

2. The metadata files required by the engine are invalid or non-existent

Error output

Error while starting up the engine: failed to build engine state - No such file or directory (os error 2)

These are the files created as a result of ddn supergraph build local. If these files do not exist, then it can be recreated by running the command.

Make sure the files are mounted to the engine container and the paths to it configured using the environment variables mentioned in this section.

By default the CLI generates these files inside engine/build of the project directory and this directory is copied when building the engine image by the following Dockerfile specified in the dockerfile field of the default docker compose file.

FROM ghcr.io/hasura/v3-engine
COPY ./build /md/

3. The engine version is not up to date to handle new metadata objects

New features introduced in DDN may have new metadata objects or fields associated with it. If your metadata uses any of these new objects but the engine version you are running is an older version that doesn't support these objects, then the engine will fail to startup. This can be resolved by using the latest engine version as mentioned in this section.

ddn run docker-start is using a different ddn binary than the one in the current shell.

The ddn run command is just a convenient way to run arbitrary commands defined in the scripts section of .hasura/context.yaml of the project directory.

The docker-start is just the name of the script defined in this file. You can see the definition of the script by going to .hasura/context.yaml.

As these scripts run in a new shell, the DDN CLI must be present in the path for it to be invoked correctly when the script is run.

How do I check that all the required dependencies for the CLI are installed?

The DDN CLI provides a ddn doctor command that checks that all the required dependencies are installed.

ddn doctor Output

$ ddn doctor
3:23PM INF Evaluating the dependencies of DDN CLI...
DDN CLI location: "/usr/local/bin/ddn"
DDN CLI version: "v2.15.0"
+------------------------------+--------+-----+
| Criteria                     | Result | Fix |
+------------------------------+--------+-----+
| Docker available             | YES    |     |
+------------------------------+--------+-----+
| Docker Engine running        | YES    |     |
+------------------------------+--------+-----+
| Docker Registry reachable    | YES    |     |
+------------------------------+--------+-----+
| Docker Compose available     | YES    |     |
+------------------------------+--------+-----+
| Docker Compose version valid | YES    |     |
+------------------------------+--------+-----+
| Control Plane reachable      | YES    |     |
+------------------------------+--------+-----+
| DDN CLI Authenticated        | YES    |     |
+------------------------------+--------+-----+

How do I specify the latest engine version for local development?

The ddn run docker-start command uses the --pull flag in the docker-start script when bringing up docker containers, and so will use the latest engine version. If you're running adocker compose command directly, then add the --pull flag to get the latest engine version.

Why are traces are not showing up for local development?

The local engine container and all connector containers send traces to the OpenTelemetry Collector container which is defined by default in the docker compose file initialized by the DDN CLI.

Traces are then exported to a cloud endpoint by the OpenTelemetry container as defined in the otel-collector-config.yaml file initialized by the CLI. For this, the OpenTelemetry Collector requires a PAT token.

If you are not able to see traces during local development:

1. Make sure you are logged in to the DDN CLI. You can check this with ddn auth print-pat. If not, log in by running ddn auth login.
2. Make sure that your OpenTelemetry Collector container is running.
3. If you are running the docker compose command directly, then make sure that the environment variable HASURA_DDN_PAT is passed to the OpenTelemetry Collector container. The value for this env var would be the output of the ddn auth print-pat command. If you are running ddn run docker-start, then this is already handled for you.
4. If you are seeing the issue when running ddn run docker-start, then it could be due to the docker-start script using a different binary to the one defined in the current shell.

I'm unable to use the latest features in my project.

If you are not able to see newly introduced features, then it could be because your metadata is outdated. New features like subscriptions may need corresponding changes to your metadata. If your metadata was initialized by an older version of the CLI, then these features may not be available and you may need to upgrade your metadata