Troubleshoot App sign-in and data

Each entry starts with what you see: in the App, in the browser console, or in the browser’s Network tab. Messages in quotes are the text work.studio sends, which the SDK passes on as the error’s message. The requests themselves are on App HTTP requests.

Find the failing request first

1. Open the App in the browser, then the developer tools’ Network tab, and filter on /api/v1/workflow/.
2. Reproduce the problem. Look at the failing request’s address, its status and its answer.
3. Match the status and message below.

The address tells you a lot on its own. Data calls go to https://api.work.studio/api/v1/workflow/data/collections/<collection>/records. If yours go somewhere else, see Every data call fails, or nothing ever saves.

Data calls

403: “This App does not keep data in ‘notes’”

The App doesn’t declare the collection, or the person signed in before it was declared. The person’s sign-in lists the App’s collections as they were when they signed in.

1. Add the collection to data in workstudio.app.yaml.
2. Run npx workstudio apps apply.
3. Sign out of the App and in again. Without that, the sign-in picks up the new collection when it renews, within about 15 minutes.

Check the spelling too: the name in your code must match collection: in the manifest exactly.

403: “‘notes’ is not kept per person, so an App’s people cannot use it”

The environment already has a collection with this name that keeps its records together rather than per person, for example one made in Flow for your automations. An App’s people only use collections whose records are kept per person. Give the App’s collection a name no other collection in the environment uses, then apply and sign in again.

403: “An App’s people use the collections the App declares; they cannot create, change or delete one”

The App’s code tried to define, change or delete a collection. Collections are declared in workstudio.app.yaml and made by npx workstudio apps apply, never from the App.

403: “This endpoint is not available to app end users”

The App called something only your organization’s members can use. An App reaches work.studio through the App SDK; a call it doesn’t offer isn’t available to the App’s people.

404: “Record not found”

The record doesn’t exist, or it’s someone else’s: each person reads only their own records, unless the collection is shared by a members-only App. collection.get(id) returns null for this, and collection.update(id, …) throws an AppError with status 404, “That record could not be found.”

413: RECORD_TOO_LARGE, “Records are limited to 1 MB”

The record’s JSON is over 1 MB, so it wasn’t saved. The message says how big it was. Keep pictures and documents in app.files and save the file’s id in the record instead.

400 with a message

The request itself was wrong, for example a field value the collection can’t take. The message says what to fix.

409: STORE_CREDENTIALS_NOT_CONFIGURED

The environment keeps its data in a store whose connection has no credentials. Someone in your organization who manages the environment’s data store needs to finish setting up that connection.

500 or 502 with an errorRef

“Managed data operation failed” (500) or “A service this request depends on is unavailable” (502). Something failed on work.studio’s side, not in your App. Try again. If it keeps happening, contact support with the errorRef from the answer.

Every data call fails, or nothing ever saves

The App is calling the wrong address. Look at where the data calls go in the Network tab:

• Not https://api.work.studio: the App was built with an old or hand-written .env.local. Run npx workstudio apps apply, which writes VITE_WORKSTUDIO_API, then build and deploy again.
• The App’s own address, answered with HTML: VITE_WORKSTUDIO_API points at the App instead of the API. The SDK reads the page that comes back as if it were data, so lists come back empty and nothing you save is kept. Fix .env.local as above.
• No answer at all, and a Content Security Policy error in the console: on workstudio.run a page may only call its own address, work.studio and the origins in hosting.connectOrigins. The SDK throws an AppError with code NETWORK, “Could not reach the service.”

Sign-in

401, and SignInRequired: “Your sign-in has expired. Please sign in again.”

The person’s sign-in ran out or was ended. Catch SignInRequired and call app.auth.signIn().

A members-only App turns a person away

The App is members-only (signIn.audience: members), and the person’s verified email doesn’t belong to a member of your organization. The sign-in fails with status 403. The swap’s answer has "error": "invalid_target" and "code": "NOT_A_MEMBER"; the SDK throws an AppError with that message. Add the person to your organization, or have them sign in with their work email.

A person is signed out by themselves

On a renewal, the platform refused the person with invalid_target: it no longer lets them into the App, for example because the App’s sign-in was turned off or they left a members-only App’s organization. The SDK signs them out. Someone removed from your organization can keep access to a members-only App for up to 15 minutes, until their sign-in renews.

The sign-in page says “Invalid parameter: redirect_uri”

The page you started sign-in from isn’t one of the App’s web sign-in addresses. Add its origin, such as http://localhost:5173, to origins under signIn.clients in workstudio.app.yaml and run npx workstudio apps apply. Every workstudio.run address of the App is added for you. If your dev server started on another port because 5173 was taken, use that port’s origin, or free the port.

“That sign-in link has expired. Please sign in again.”

The page came back from sign-in, but the sign-in it started is gone, for example because it was opened in another tab or the browser’s storage was cleared in between. Start sign-in again. The error’s code is STALE_SIGN_IN.

429 when signing in or renewing a sign-in

Too many sign-in swaps came from one IP address: more than 300 in a minute, or 20 refused ones within 5 minutes. After 20 refusals, every swap from that address is refused until the 5 minutes are up, even good ones. The answer has a Retry-After header. Repeated refusals usually mean the App keeps sending an expired or wrong token; sign the person in again rather than retrying.

No Google or Apple button on iPhone

On an iPhone or iPad build, the sign-in page offers email and password only, and Apple sign-in isn’t offered on any platform. Keep Email and password turned on for an App with an iPhone build: saving without it is refused with “on iPhone this App can offer email sign-in only”.

“Sign-in was cancelled.”

The person closed or cancelled the hosted sign-in page. The error’s code is what the sign-in page sent, such as access_denied.

AI and plans

These aren’t failures: show them to the person as what they are.

Status	Error	What it means
429	AllowanceUsed	The person has used this month’s AI allowance in the App. It resets on the 1st (UTC)
429	AiPaused (APP_FREE_POOL_PAUSED, APP_AI_PAUSED)	AI is paused in the App for now: their plan’s shared pool, or the App’s own AI budget, is spent. resetAt says until when
402	CreditsUsedUp (CREDITS_USED_UP)	The person is out of credits for now
403	NotForYourPlan (NOT_FOR_YOUR_PLAN)	Credit packs come with some plans only

For errors from npx workstudio deploy and from App functions, see Ship an App.