Troubleshooting

Start with the closest, least expensive layer: local configuration, inference, Pulumi, SSH, containers, and finally the control plane. Do not delete data merely to “start from scratch.”

The preview cannot find chalupa.yml

Confirm the path:

export DEMO_CONFIG="$PWD/chalupa.yml"
test -f "$DEMO_CONFIG"

Run validation from the Chalupa repository:

cd "$CHALUPA_HOME"
task validate CONFIG="$DEMO_CONFIG"

If a path relative to the Compose file fails, check which directory your Chalupa version resolves it from.

A service is missing

Each entry in services must exactly match a key in Compose:

task preview CONFIG="$DEMO_CONFIG"

The output lists the included services. Do not add an exception to the engine; correct the declarative configuration.

A dependency is broken

Chalupa prunes depends_on references to unselected services. If a selected service still needs that dependency at runtime, include it explicitly in chalupa.yml.

The tunnel does not open

Check the known state first:

task status CONFIG="$DEMO_CONFIG"

Then run:

task tunnel CONFIG="$DEMO_CONFIG"

Investigate:

• the selected stack;
• connectivity to port 22;
• the available SSH key;
• an unexpected host-key change;
• the inferred ports.

Do not expose database ports publicly as a temporary shortcut.

The seed reports that no tunnel is open

task seed expects services on localhost. Keep task tunnel running in another terminal and verify the service port before retrying.

If the seed stopped partway through, use the project's documented resume procedure. Do not run task data-nuke.

The environment appears stale

stale means the deployment appears active, but Chalupa has not received a recent signal.

Inspect the droplet without printing secrets:

systemctl status chalupa-agent
journalctl -u chalupa-agent --since "10 minutes ago"

Look for network, system-clock, URL, signature, or payload-format errors. Redact headers and bodies before sharing logs.

The control plane rejects the signature

Common causes include:

• a timestamp outside the accepted window;
• a reused nonce;
• signing a different path from the one sent;
• serializing the body again after signing;
• a different key;
• a malformed v1= header.

Synchronize the clock and sign the exact body bytes. Do not print the HMAC key to compare it.

A run does not appear

Validate:

• a valid slug in environmentSlug;
• a unique sourceRunId;
• a passed, failed, or errored status;
• duration in milliseconds;
• HTTP or HTTPS artifact URLs;
• the batch size.

The endpoint returns 202 when it accepts the ingest request.

The countdown does not match exactly

The countdown is derived from discrete checks. Compare idleChecks, checkIntervalSeconds, limitMinutes, and the time of the latest signal. A small difference is expected; a frozen counter alongside fresh heartbeats is not.

The environment is sunk but still has cost

Review the breakdown. Compute should be zero, but a persistent volume can continue to incur estimated cost. The provider invoice remains authoritative.

Before escalating

Collect these details without secrets:

• output from bun preview-compose.ts;
• Bun, Pulumi, and Chalupa versions;
• a demo name or redacted identifier;
• UTC timestamps;
• agent status;
• the API error code;
• whether the problem affects compute, storage, or both.