Troubleshooting

I can’t sign in#

The console says access is restricted#

Your GitHub account has neither an active Codara Cloud organization membership nor a matching invitation.

• Ask an organization owner or admin to invite the verified email shown on your GitHub account, then open the one-time link they send.
• If you are Codara staff, confirm your platform-users team membership is active. GitHub organization membership alone is not enough.
• An expired, revoked, already-used, or differently addressed link cannot be reused; ask for a fresh invitation.

See Getting access.

Google sends me to the no-organization screen#

Google verified successfully, but that Google identity is not yet connected to your existing GitHub-backed account. Sign out, sign in with GitHub, then open Settings → Account → Connect Google. Do not rely on both providers returning the same email; Codara deliberately does not merge accounts from email text alone.

The console looks signed in but everything is empty#

Your session has probably expired — sessions last 7 days. Sign out and back in.

My app was created but never started#

If you created the app anywhere other than the console’s deploy wizard, no build was started and the app is pointing at a placeholder image. Trigger the first build:

$ codaracloud deploy my-api --source

My deploy did nothing#

codaracloud deploy <app> with no flags restarts the current image — it does not build. Pass --source, --branch or --commit.

Pushing to GitHub doesn’t deploy#

Work through these in order:

• Is the GitHub App installed on the repository’s owner? Install it at github.com/apps/codara-cloud.
• Did you push the branch the app tracks? Check the app’s configured branch.
• Are automatic deploys on? They can be disabled per app.
• Did the push match a watch path? If not, it is recorded as a skipped deploy — look for it in the deploy list.
• Has the organization reached a plan limit? Each plan includes a number of build starts per month, and failed builds count; once used up, builds cannot start until next month. A cancelled or expired subscription allows no new deploys and pauses running workloads.

The build failed#

“Could not detect a build strategy”#

Nothing recognisable was found at the build root. Add a Dockerfile, or check that your root directory points where you think it does.

The wrong builder ran#

Detection order is Dockerfile, then nixpacks.toml, then Railpack, then static assets. Nixpacks is opt-in — without that file, a Node or Python repo goes to Railpack.

An environment variable was missing during the build#

Environment variables are runtime only and deliberately invisible to the build. If your build genuinely needs a public value, commit it to a file your framework reads at build time (for Next.js, .env.production), or build with your own Dockerfile and pass it as a build argument. Build arguments do not reach Railpack, Nixpacks or static builds. Never put a secret in either. See Building and deploying.

The build timed out#

Builds are capped at 30 minutes. Reduce what you are building — better layer caching, a smaller context, fewer dependencies compiled from source.

The build succeeded but the app isn’t up#

A successful build only means the image exists. If the rollout never became healthy, the release is marked failed and your previous version is still serving.

• Wrong port. The most common cause. Codara sends traffic to port 8080 unless told otherwise, and injects the port as PORT. Bind to that, and bind to 0.0.0.0 rather than 127.0.0.1 — a container listening only on loopback is unreachable.
• Crash on startup. Check the logs. Output from a container that was already replaced is under Logs → History.
• Failing health check. If the path you configured does not return a success status, the pod never becomes ready.
• A climbing restart count on the Metrics tab confirms a crash loop.

My custom domain doesn’t work#

For a hostname that should work:

• Check the DNS and certificate status on the app’s Domains tab. The CLI does not show this.
• Confirm the CNAME points at customers.codara.cloud and has propagated.
• For an external domain, confirm the _codara-verify TXT record shown by Codara is published. Once verification succeeds, cert-manager requests the TLS certificate automatically; no Codara-owned domain is required.
• A status of unknown is usually a slow DNS lookup rather than a failure — check again shortly.

A sleeping app won’t wake#

Three situations where wake-on-request does not apply:

• The request arrived on a custom domain. Only a request to the app’s codara.cloud address wakes it. Keep a service with a custom domain on Always on.
• The request came from another app internally. Private traffic bypasses the waking layer, so a private dependency must not sleep.
• Its environment is paused, or Codara has suspended it (for example over a spend cap).

Wake it manually with codaracloud apps wake <app>.

I can’t find my logs#

Live logs show only what the running containers still hold. Output from earlier containers, across restarts and deploys, is under Logs → History for as long as your plan keeps it: 1 day on Starter, 7 days on Standard and 30 days on Pro and Scale. Build logs are deleted after 24 hours. To keep logs longer, ship them to your own service from inside the app. See Logs and metrics.

Metrics don’t go back far enough#

Metrics can be viewed for up to the last 30 days: 30d is the longest window you can request.

Deploys are being refused#

A 402 means the organization’s plan does not allow the request. The error body says why:

• plan_limit_exceeded names the limit, with the allowed and current values. Remove resources you no longer need, or choose a larger plan in Settings → Billing.
• subscription_not_active means the subscription or trial has ended, or a payment is overdue. While overdue, creating resources is refused at once; deploys and wakes keep working for 14 days.

Reaching a plan limit never stops what is already running; an ended subscription pauses it. See Plans and capacity.

“Refusing to guess” when creating an app or job#

The workspace has more than one project and you did not say which to use. This is deliberate — Codara will not place a service into a project on your behalf, because that is how unrelated services end up piled into one workspace.

Either name the project:

$ codaracloud projects list --client my-workspace$ codaracloud apps create my-api --client my-workspace --project storefront --repo my-org/api

…or, more often the right move, create a project for it. A project is normally one product with its own repository.

The related no_workspace error means the workspace has no projects at all yet — create one before adding services.

A command says my app name is ambiguous#

The same name exists in more than one project or environment. Pass scope explicitly where the command supports it — and note that env, domains, logs, metrics and apps get accept no scope flags at all and always resolve against your default workspace and production. Use the console for those cases.

“namespace too long” when creating an app#

The workspace, project and environment slugs are combined and capped at 63 characters. The error names which one to shorten. Slugs cannot be renamed without breaking URLs, so this is usually a reason to create a new project with a shorter name.

A token stopped working#

• Check it has not passed its expiry date.
• Check its scopes cover what you are calling — a 403 names the scope that was required.
• A token created with no scopes can only reach /v1/me.
• A token bound to one workspace cannot touch another workspace’s resources.
• If it was created in the console and you need db:connect or bucket scopes, recreate it with the CLI — the console’s list omits those.

Still stuck#

Bring the app name, the workspace, the deploy ID and the exact error. If a build failed, copy the build output before it ages out — after 24 hours it is gone and the failure is much harder to diagnose.