Skip to main content

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​

SymptomCause and fix
Could not tell how to run this folderNo 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" scriptVite apps need a build script, or build in tc.json
Node project has no "start" script and no server.js/index.jsAdd 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_LARGEBundles 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 checkThe 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 errorsThe message names the field. See tc.json reference
NAME_BEING_FREEDA project with that name was just deleted and its teardown is finishing. Try again in a few seconds

Opening an app​

SymptomCause and fix
"You don't have access" pageThe project's access doesn't include you. The page names the owner to ask. New projects start as Only me
"Archived" pageThe 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" pageAn admin pulled the kill switch for the project or its owner. Contact IT
Signed out of one app signs you out of allExpected: 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 applyAccess 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​

SymptomCause and fix
The app shows no rows, the Studio shows themRow-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 violationThe 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 codeA 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_TIMEOUTThe query ran past the statement timeout (15 s by default). Add an index or narrow the query
/_tc/db returns 404The Data API exists once the project has a deployment. Deploy first

Storage​

SymptomCause and fix
STORAGE_FORBIDDENSomeone else's file in a private bucket. Add the reader's app role to the bucket's readRoles, or share a signed URL
STORAGE_EXISTSA file already exists at that path. Pass upsert: true to replace it (uploader, editor or admin only)
STORAGE_TYPE_NOT_ALLOWEDHTML, SVG, scripts and executables are refused because files are served from the app's origin
An <img> from a signed URL breaks laterSigned URLs expire. Store the path and sign when rendering

Integrations​

SymptomCause and fix
ACCESS_PENDINGThe 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_DENIEDAn approver said no, or approved a narrower grant (for example read-only). Work within it, or ask again with a better purpose
CONNECT_REQUIREDThe 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_DENIEDThe 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_ERRORThe vendor itself returned an error; err.details has its response
A job stays pending_accessApprove the request; the job re-runs automatically when the grant lands

More in Integrations.

CLI and MCP​

SymptomCause 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 refusedOn vastframe cloud, set TC_TENANT=<slug> when the API address isn't your organization's host
MCP deploy asks for a purposeThe code uses an integration that needs approval. Give a one-line purpose written for the approver
Was this page helpful?