Start with the exact error, project ID, signed-in account, and time. Confirm whether the failure is in Dashboard, Studio, the application server, the hosted API, or an external integration.
| Symptom | Checks and recovery |
|---|---|
| Cannot find a project | Account, invitation status, project configuration; join guide. |
| Missing entity or field | Deployed schema and spaces; access guide. |
| Create/Save unavailable | Role, read-only field, unsaved changes, project restriction; editing. |
| Schema mismatch after deploy | Deployment completion, application config, refreshed Explorer schema; schema errors. |
| Studio shows Project not found | The project was deleted, the link has a wrong project ID, or your account is not a member of it. In a self-hosted Studio, also check the project ID passed to FlexkitStudio and that the Flexkit API handler route is mounted. |
| Desk has no entities | The project has no schema yet. Build it with the agent, or run flexkit deploy for a schema managed from code. |
Studio shows an old schema after editing flexkit.config.ts | The Studio renders the deployed schema, not the local file: run flexkit deploy for that project and reload; iterating your schema. |
| Studio shows No access | Your account is not a member of that project; ask an administrator for an invitation; members. |
flexkit deploy refuses flexkit.config.tsx | Rename to flexkit.config.ts, replace icon components with lucide names, make hidden/readOnly booleans, remove extensions, basePath and commands; schema configuration. |
Deploy fails at schema[i].attributes[j].validation (Attribute "x" of entity "y": validation ...) | The Zod rule cannot be enforced by the Studio form: refine(), superRefine(), check(), transforms, or a JSON Schema keyword or format outside the supported set. Use built-in checks such as min, max, length, regex, int, email, uuid, url; attribute reference. See Validation. |
| API authentication failure | Endpoint, credential type, revoked token, role; authentication. |
| Browser request blocked | Actual Origin, preflight, credentials; CORS. |
| Search misses a known record | Project, filter, searchable fields, indexing; search. |
| Upload fails | Permission, response error, storage and request constraints; assets. |
| AI cannot complete work | Credits, project state, attached tool, run summary; runs. |
| Run waits indefinitely | Pending/expired approval and reviewer authority; approvals. |
| Tool cannot be discovered | Production URL, deployed handler, signing secret; tools. |
| Data reads or writes stopped | Restriction cause; project lifecycle. |
Retry only after checking whether the original action had partial effects. A network error does not prove a write or external side effect never occurred.
If the checks do not resolve the issue, collect a minimal reproduction and redacted diagnostic identifiers for support.