Troubleshooting

Finding the cause of a failed build, an app that stays pending, an address that does not answer, or a change you are not allowed to make.

6 min read

Start from what you see. Each part below says what usually causes it, where CloudJod shows the reason, and what to do about it.

A build failed

• The app's Builds tab shows each build's whole output. The reason is usually near the end: a dependency that would not install, a step in the Dockerfile that failed, or a guess about how to build the code that was wrong. See Apps → Builds, which also says how to choose the right way to build it.
• A failed build changes nothing that was running. The last release keeps serving until a build succeeds.
• Code from a repository has to be connected first, on the app's Deploy tab: Apps → Getting code in.
• cloudjod build APP --wait follows a build to its end from a terminal.

An app stays pending

• No deployment yet; push code or set an image to start this app means exactly that: the app exists and nothing has been deployed to it yet. See Deploy your code.
• No host can take this workload, followed by the reason, means no server has room for it as it is sized, or none of the servers it may run on can take it. Make it smaller under Scaling, or give it more room: Your own servers.
• An image that cannot be downloaded is tried again after a wait that starts at twenty seconds and doubles up to ten minutes, so a registry that limits downloads is not asked again every few seconds. Deploying, restarting or changing the app tries again at once.

The address does not answer

• The app has to listen on the port given in its settings. It is also given that number as PORT.
• A copy of the app is sent traffic only once its health check path answers with any 2xx or 3xx. One that never answers there is never sent any: Create an app.
• The first request to a new address can take a few seconds while its certificate is issued.
• Logs shows what the app prints. An app that starts and stops at once usually says why there: Apps → Logs.
• An app only your team may open does not answer anybody else: Apps → Who can open it.

An app keeps stopping

• The app's page says why the last copy stopped: the status it exited with, or that it was stopped for using more memory than it is allowed.
• A copy that stops on its own is started again on the next pass, about ten seconds later. One that keeps stopping is started again after a wait that doubles each time, up to five minutes, so it cannot use the whole machine starting and stopping.
• An app that keeps stopping with nothing in its logs is often out of memory. Give it more under Scaling. cloudjod usage APP shows how much each copy uses, and how often it was stopped for using too much.

An app cannot reach its database

• An app is given its connection string, DATABASE_URL or REDIS_URL, at its next deploy after the database is attached. Deploy it again after attaching one: Databases → Connect an app.
• An app with two databases of one kind keeps DATABASE_URL for the first, and the second has a variable named after it, such as DATABASE_URL_REPORTS_DB.
• Databases have no public address. Only your organization's apps can reach them, over its private network: Security → Your apps, kept apart.

A custom domain does not work

• A custom hostname is served only once its ownership TXT record is found. HTTPS is issued once traffic reaches the edge through the CNAME as well: Domains and DNS → Connect a custom domain.
• A change to DNS is seen everywhere only after the old records' TTL. Remove old records that still send some visitors elsewhere.
• A root domain such as example.com cannot have a plain CNAME. Use your DNS provider's ALIAS, ANAME or CNAME flattening.

You are told you may not

• Your role decides what you can change, and areas can narrow it to parts of the organization: Roles and Areas.
• Some people's changes wait for an owner's approval instead of happening at once. The dashboard says so, and the API answers 202: Trust and approvals.
• A token acts as the person who made it, never above their role: API tokens and VPN devices.

A coding tool cannot connect

• Tools connect to https://api.cloudjod.com/v1/orgs/<organization>/mcp, by signing in or with a token: Develop → Connect a tool.
• A tool can do what the person who connected it can do, and no more: Develop → It acts as you.
• A change refused because files are locked was stopped by another agent's lock on them. The Agents board shows who holds it: How agents stay out of each other's way.

You cannot sign in or get an account

• Anybody can create an account here. To join an existing organization, ask one of its owners for an invitation: Bringing people in.
• This installation sends no email, so a forgotten password cannot be reset by email. Ask the people who run it.
• With two-factor sign-in on, a recovery code works once in place of a code from your authenticator app.

Still stuck

The audit log records who changed what and when. On the public documentation, the search box beside every guide finds the pages that mention a word or an error message, and the Glossary explains the words CloudJod uses.