Troubleshooting

Start with the symptom, then check the smallest boundary first.

ObjectOS does not start

Read the last lines of the log before anything else. A large class of startup failures here is a deliberate refusal, not a crash: the runtime checks the configuration it was given, prints a fatal error naming the variables that disagree, and exits. Those messages name the problem exactly, and no amount of restarting will change the outcome.

The refusals you are most likely to meet:

If the log shows no fatal error, check the ordinary causes: container logs for the failing service, a port conflict, and a missing auth secret when authentication endpoints are expected.

The app is not the one you expected

The app a deployment serves comes from exactly one place, and which place is a decision the deployment declares — see Boot modes. When the running app is not the one you published:

• Confirm which mode this deployment is in. If no artifact reference is set, the runtime is serving the metadata authored in the image plus whatever was installed into it — publishing a new artifact changes nothing until the deployment names it.
• Check the boot banner, which names the app that was actually loaded.
• An integrity pin that does not match refuses the boot and prints both the expected and the actual digest. Those two being printed together is the point: it distinguishes a republished artifact from a substituted one.
• Unpinned, with the artifact host unreachable, the boot fails loudly. There is no cache fallback on the unpinned path — nothing could authenticate a cached copy. Orchestration retries; the runtime never invents a different app.
• Pinned, with the host unreachable, a locally cached copy may serve — but only one whose bytes still hash to the pin, and it says so with a warning. The cache is re-hashed on every read; a filename is never the authority.
• Setting a retired artifact variable does not select an app. One of them refuses the boot outright; the others are read by nothing at all, so the deployment boots as if you had set nothing. Retired names lists them against their replacements.

Login fails

Check:

• OS_AUTH_SECRET is configured;
• public URL and callback URL match;
• OIDC discovery URL is reachable from ObjectOS;
• trusted origins include the public domain;
• cookies are scoped to the deployment's public hostname.

User cannot see records

Check:

1. Correct deployment hostname.
2. User belongs to the expected organization.
3. Object read permission.
4. Row-level security.
5. Sharing rules or record shares.
6. Field security if only some fields are missing.

Settings are not editable

A setting may be locked by an environment override. Effective settings resolve in this order:

Environment -> Tenant -> User -> Default

If the environment provides a value, runtime edits should be rejected instead of silently overwriting it.

Webhooks or jobs do not run

Check:

• the artifact requires list includes the needed capability;
• the ObjectOS image includes the optional service package;
• queue/job service configuration is available;
• outbound network access to the target is allowed;
• delivery logs or job runs are visible in Setup diagnostics.

Database errors

Check:

• database URL and driver type;
• network access from ObjectOS to the database;
• credentials and TLS options;
• schema sync/migration logs;
• storage persistence if using local SQLite.