# Troubleshooting

Solutions to the most frequent errors when deploying with DeployAlly.

# Template Validation

# "validation failed: missing required input"

Error: validation failed
  - inputs.required: WEB_HOSTNAME has no default and no value provided

Cause: The template declares a required input that was neither passed via --input nor answered in the wizard.

Fix:

deployally deploy --species memos --instance-uid memos-001 \
  --input WEB_HOSTNAME=memos.example.com \
  --apply

To discover all required inputs:

deployally validate --species memos

# "validation failed: archetype unknown"

Error: archetype "applikation" is not valid

Cause: Typo in the template's archetype field. Only six values are accepted: application, asset, static, worker, multi_component_saas, network_appliance.

Fix: Use one of the official archetypes. See Templates.

# Auto-Provision

# "no running asset matched class X"

Error: needs.options[0] requires asset class "mysql"
  No running container has label ccs.systems/asset_class=mysql

Cause: The application declares a dependency on an asset that is not available on the server.

Fixes:

# Bring up the asset manually
deployally deploy --species mysql --instance-uid mysql-shared --apply

# Or use auto-provision (recommended)
deployally deploy --species wordpress --instance-uid blog-001 \
  --input WEB_HOSTNAME=blog.example.com \
  --provision-missing-assets --apply

# "auto-provision: asset image variant not found"

Error: variant "mysql-8.4" not declared in template "mysql"

Cause: The consumer template declares a specific asset variant that does not exist in the asset's template.

Fix: Use the default variant by omitting --variant, or update the consumer template to reference a valid variant.

# DNS and TLS

# "DNS preflight failed"

Error: DNS preflight failed for memos.example.com
  Expected A record pointing to <server-ip>, got nothing

Cause: The domain has no A record pointing to the server where the deploy is running. Without that, Let's Encrypt cannot issue a certificate and Traefik responds with the default cert (404).

Fix:

# Check domain resolution
dig +short memos.example.com

# If empty, configure DNS first:
#   memos.example.com  A  <server-ip>

# Wait for propagation and redeploy

# Container comes up, but Traefik responds 404

Cause: Traefik labels were emitted, but the cert resolver name doesn't match the one configured in Traefik (different alias, custom resolver name, etc.).

Fix: DeployAlly uses a canonical cert resolver (tls.certresolver). Confirm Traefik was configured with the same resolver name. If you customized it, align Traefik's configuration — or use the traefik template from the catalog, which is ready to go.

# Containers

# "Port already in use"

Error: bind: address already in use (port 3306)

Cause: Another process on the host is occupying the port. Common when another container or systemd service already runs on the same port.

Fix:

# Find out what's using it
sudo ss -tulpn | grep 3306

# Stop the conflicting service (example: mysql systemd)
sudo systemctl stop mysql

# Redeploy
deployally deploy --species mysql --instance-uid mysql-001 --apply

# Container "unhealthy" after deploy

Container is running but healthcheck failed: exit code 1

Cause: The service inside the container does not answer the command declared in healthcheck. Common with apps that take a while to boot (database running migrations, postal spinning up workers).

Diagnosis:

# View container logs
docker logs <container-id>

# View healthcheck detail
docker inspect <container-id> --format '{{json .State.Health}}' | jq

Fix: If the service is starting normally but takes time, increase start_period in the template. If the error is configuration-related, fix the corresponding input.

# Container restarting in a loop

Cause: The main process is crashing before the healthcheck can run — usually a config error or an invalid environment variable.

Fix:

# View the last logs
docker logs --tail 100 <container-id>

# View the last restart's exit code
docker inspect <container-id> --format '{{.State.ExitCode}}'

Common: secret expecting a specific format (e.g., RAILS_SECRET_KEY must be 128 hex chars). Check the template and confirm the input/secret is being generated correctly.

# Reflang

# "reflang: undefined variable"

Error: ${input.MYSQL_PORT} is not defined

Cause: Template references an input that is not declared in inputs.required, inputs.optional, or inputs.advanced.

Fix: Declare the input in the template or use a literal value. For substitution with fallback:

port: ${default(input.MYSQL_PORT, 3306)}

# "reflang: provider chain exhausted"

Error: secret DB_PASSWORD has no value (tried: input, env, generate)

Cause: The secret's provider chain returned no value. Common when the template depends on an input that wasn't passed and has no generate: fallback.

Fix: Add a generate: fallback to the secret:

secrets:
  DB_PASSWORD:
    provider: input
    generate:
      type: hex
      length: 32

# Nested substitution doesn't work

Correct syntax for indirection: ${input.${SLUG_UPPER}_DOMAIN} — the engine resolves ${SLUG_UPPER} first, then reads input.<result>_DOMAIN. Legacy templates with different syntax need to be migrated.

# API and Connection

# "401 Unauthorized" from the API

Error: API returned 401 Unauthorized

Cause: API key is invalid, revoked, or pointing at the wrong environment (test vs prod).

Fix:

1. Verify the header is Authorization: Bearer da_xxx
2. For the test environment, use a key with the da_test_ prefix on dev.sys.deployally.com
3. Create a new key in the dashboard: Settings → API Keys

# "Failed to connect to API"

Error: connection refused

Cause: Server unavailable, firewall blocking, or DNS not resolving.

Diagnosis:

curl -I https://sys.deployally.com/api/v1/health
dig sys.deployally.com

# Logs and Debug

# Enable verbose logs

RUST_LOG=debug deployally deploy --species memos \
  --instance-uid memos-001 --apply

# Inspect the rendered manifest

cat /opt/deployally/manifests/<instance-uid>/manifest.yaml

The manifest shows the spec after all Reflang substitutions are applied — useful to understand exactly what was sent to Docker.

# Test Docker connectivity

docker info
docker network ls

# Support

If the problem persists:

1. Collect the output of deployally validate --species <X> and the affected container's logs
2. Check the FAQ
3. Open an issue at github.com/devborlot/deployally-client
4. Email: support@deployally.com