Skip to main content

Troubleshooting

This guide covers common issues when running DoubleDino.

DoubleDino will not start​

Check required configuration​

DoubleDino requires:

DD_MODE
DD_SOURCE_URL
DD_SECRET_KEY

Proxy mode also requires:

DD_AUTH_KEY

Clone mode also requires:

DD_DEST_URL

Check that all required variables are available in the environment where DoubleDino is running.

Example:

env | grep DD_

Cannot connect to source database​

Common causes:

  • Incorrect connection string.
  • Database is not reachable from the DoubleDino host.
  • Firewall or network rules blocking access.
  • Invalid credentials.
  • Missing database permissions.

Verify the connection outside DoubleDino using the same credentials.

Example:

psql "postgres://user:password@host:5432/database"

The DoubleDino host must be able to reach the source database.

Proxy starts but requests fail​

First verify the service is running:

curl -G "http://localhost:8080/meta" \
  -H "x-api-key: your-key"

Expected:

{
  "status": "online",
  "type": "postgres"
}

If this fails:

Check:

  • DD_HTTP_PORT
  • Network access.
  • Reverse proxy configuration.
  • DD_AUTH_KEY

Authentication failures​

All proxy requests require:

x-api-key

Example:

-H "x-api-key: your-key"

Common causes:

  • Missing header.
  • Incorrect API key.
  • Different environment variables between startup and client.

Clone fails​

Check:

Source and destination types​

Clone requires matching database types.

Supported:

PostgreSQL → PostgreSQL
MySQL → MySQL
MariaDB → MariaDB
MongoDB → MongoDB

Unsupported:

PostgreSQL → MySQL
MongoDB → PostgreSQL

Destination permissions​

The destination database must allow DoubleDino to create and write the required data.

Verify:

  • Database exists.
  • User has write permissions.
  • Network access is available.

Transformed values are different than expected​

DoubleDino transformations depend on:

DD_SECRET_KEY

The same source value will only produce the same transformed value when the same secret key is used.

Changing:

DD_SECRET_KEY

creates a different transformed dataset.

Developer cannot query expected data​

Check:

  1. The query is valid for the underlying data source.
  2. The developer is using the correct endpoint.
  3. The source connection has access to the required data.

Examples:

SQL databases:

/query

Redis:

/redis

Logs:

/logs

Running behind a reverse proxy​

If DoubleDino is behind Nginx, Traefik, or another proxy, verify:

  • The upstream port matches DD_HTTP_PORT.
  • The proxy can reach the DoubleDino process.
  • Required headers are forwarded.
  • TLS termination is configured correctly.

Example:

Collecting diagnostic information​

When investigating an issue, collect:

  • DoubleDino version.
  • Operating mode.
  • Data source type.
  • Relevant logs.
  • Startup configuration (without secrets).

Never share:

  • DD_SECRET_KEY
  • DD_AUTH_KEY
  • Database passwords.

Still having issues?​

Before reporting an issue, verify:

  1. DoubleDino can reach the source.
  2. Required environment variables are set.
  3. Authentication headers are correct.
  4. Logs are available.

Include the relevant error message and operating environment when requesting support.