Troubleshooting
Start with the error code. Every vastframe error, from the SDK, the API, the CLI or MCP, carries a code and usually a fix that says what to do. The error code reference lists them all.
Deploys
| Symptom | Cause and fix |
|---|---|
| Could not tell how to run this folder | No Dockerfile, package.json, Python requirements or index.html in the deployed folder (or in tc.json path). Add one, or set type, build and start in tc.json. See Runtimes and detection |
| Static Node project has no "build" script | Vite apps need a build script, or build in tc.json |
| Node project has no "start" script and no server.js/index.js | Add a start script |
FastAPI is in requirements but no file has app = FastAPI(...) | Detection looks for that assignment at the top level of a .py file; or set start in tc.json |
BUNDLE_TOO_LARGE | Bundles are limited to 50 MB. Exclude build output and data files; the CLI already skips node_modules and .git |
| The build passes but the deploy fails at the health check | The app must listen on 0.0.0.0:$PORT (8080 by default) and start within 90 seconds. Check the runtime log |
| Database migration failed: … | A file in db/migrations/ failed. Production is unchanged. Fix the SQL and deploy again; already-applied files are skipped |
tc.json errors | The message names the field. See tc.json reference |
NAME_BEING_FREED | A project with that name was just deleted and its teardown is finishing. Try again in a few seconds |
Opening an app
| Symptom | Cause and fix |
|---|---|
| "You don't have access" page | The project's access doesn't include you. The page names the owner to ask. New projects start as Only me |
| "Archived" page | The project was archived (unused for 90 days, or by its owner or IT). The owner or an admin can restore it from Settings › Danger zone |
| "Disabled by IT" page | An admin pulled the kill switch for the project or its owner. Contact IT |
| Signed out of one app signs you out of all | Expected: single sign-on. /_tc/auth/logout signs out everywhere |
| "Not a member yet" | You signed in with your organization's identity provider, but you aren't a member of the organization in vastframe yet. Ask an Org Admin to invite you, or to turn on auto-join for your verified email domain |
| Access change doesn't apply | Access changes apply within seconds. My team and My department follow the directory and update after the next Org Sync (every 5 minutes, or Admin › Org › Sync now) |
Data
| Symptom | Cause and fix |
|---|---|
| The app shows no rows, the Studio shows them | Row-level security is on and no policy allows this person to read. Add a policy. See Row-level security |
| Insert fails with a row-level security violation | The row doesn't pass the policy's with check, often a created_by sent from the browser. Let the column default fill it |
NO_REQUEST in server code | A per-person call (tc.db.from, tc.storage, tc.m365) ran without the request. Pass req (tc.db.asUser(req), { request: req }) or install tc.middleware() |
SQL_TIMEOUT | The query ran past the statement timeout (15 s by default). Add an index or narrow the query |
/_tc/db returns 404 | The Data API exists once the project has a deployment. Deploy first |
Storage
| Symptom | Cause and fix |
|---|---|
STORAGE_FORBIDDEN | Someone else's file in a private bucket. Add the reader's app role to the bucket's readRoles, or share a signed URL |
STORAGE_EXISTS | A file already exists at that path. Pass upsert: true to replace it (uploader, editor or admin only) |
STORAGE_TYPE_NOT_ALLOWED | HTML, SVG, scripts and executables are refused because files are served from the app's origin |
An <img> from a signed URL breaks later | Signed URLs expire. Store the path and sign when rendering |
Integrations
| Symptom | Cause and fix |
|---|---|
ACCESS_PENDING | The project needs a grant that's waiting for approval. The error names the request and approvers. It starts working when approved, with no redeploy. Show the message; don't retry in a loop |
ACCESS_DENIED | An approver said no, or approved a narrower grant (for example read-only). Work within it, or ask again with a better purpose |
CONNECT_REQUIRED | The person hasn't connected their account for a per-user integration (Salesforce). In the browser call tc.int.salesforce.connect() or follow err.connectUrl |
M365_ACCESS_DENIED | The person can't open the file in SharePoint or OneDrive. That's by design. To show the data to everyone who can open the app, the owner uses Show data to everyone with app access on the Integrations page |
VENDOR_ERROR | The vendor itself returned an error; err.details has its response |
A job stays pending_access | Approve the request; the job re-runs automatically when the grant lands |
More in Integrations.
CLI and MCP
| Symptom | Cause and fix |
|---|---|
Not logged in. Run tc login --dev. | No token saved and no TC_TOKEN set |
| Cannot reach the Hub at … | Wrong --api / TC_API, or the local stack isn't running (npm run stack:up) |
| A request names no tenant and is refused | On vastframe cloud, set TC_TENANT=<slug> when the API address isn't your organization's host |
MCP deploy asks for a purpose | The code uses an integration that needs approval. Give a one-line purpose written for the approver |
Was this page helpful?