Troubleshooting
Common problems with signing in, building a model, training and calling an endpoint, with their causes and fixes.
Signing in
"Please verify your email before signing in"
Accounts created with a password must confirm their email address first. Use the link in the email Fernfly sent when you signed up. If it has expired or you can't find it, choose Sign in with an email link on the sign-in page: using that link confirms your address too.
No sign-in email arrives
Check your spam folder. Fernfly sends at most one sign-in or password-reset email every five minutes, so a second request in that time sends nothing. Use the link from the first email.
"No Fernfly account uses that Microsoft address yet"
The Microsoft button on the sign-in page only signs in to an existing account. Sign up with Microsoft first, or sign in with the email and method you signed up with.
Building a model
The docs link finds nothing, or the wrong operations
- The docs need sign-in. Studio can only read public pages. Use an OpenAPI file instead.
- The link points too high up. Studio reads the section of the site your link points into. Link to your API reference, such as
https://docs.example.com/api, not the docs home page. - The reference is generated from a spec. Link to the spec file itself, or upload it with OpenAPI file.
Studio only keeps an operation whose endpoint appears in the docs, so a page that describes features without listing endpoints yields no tools.
The intent bar build stopped with more than 30 operations
That's expected, not an error. An intent bar works best with at most 30 tools, so Studio selects the 30 your users are most likely to ask for and waits for you. Change the selection if you like, then choose Continue building.
"We couldn't read your app's pages"
Studio couldn't load your app's address to find pages for instant search, usually because the pages need sign-in. The intent bar uses the links in your app's <nav> instead. The model isn't affected: these pages are never used for training.
"Generation already in progress for this project."
A Generate run is still going, possibly in another tab. Wait for it to finish, then generate again.
Training
Training hasn't made progress
The run's status shows Stalled and a notice reads Training hasn't made progress in N minutes. It may recover on its own and carry on. If you'd rather not wait, choose Stop: a stalled run ends at once, and its training minutes are counted only up to its last progress. Then start a new run. See Train and deploy.
"A training job is already running for this project"
Each project runs one training job at a time, and a stalled run counts as running. Wait for it to finish, or stop it on Training jobs.
"Too many training jobs running (max 3)"
You have three runs in progress across your projects. Wait for one to finish.
The trained model gets things wrong
See Training best practices. The usual causes are tools with similar names or vague descriptions, too few training pairs for some tools, and pairs that don't use your users' words.
Calling the endpoint
| Response | Cause | Fix |
|---|---|---|
401 Invalid or missing API key | The X-Api-Key header is missing or wrong. | Send the project API key. If you've lost it, see The project API key. |
403 This origin is not allowed to call this endpoint. | A browser on a site that isn't in the allowed sites made the call. | Add the site, including http://localhost:3000 while you develop, under Sites allowed to call this endpoint. |
404 No active deployment for this project | Nothing is deployed yet. | Deploy a finished run from Training jobs. |
429 with rate_limited: true | A keyless caller sent more than 20 requests in a minute. | Slow down. Server-side calls with the project API key aren't rate-limited this way. |
429 with quota_exceeded: true | Today's inference requests are used up. | Wait for 00:00 UTC, ask for grace credits, or upgrade. |
502 Inference service unavailable | The model couldn't be reached. | Retry after a short wait. |
The response has no calls
out_of_scope: true: the request has nothing to do with your tools.needs_fallback: true: the request relates to your tools, but the model couldn't produce a call. If the AI fallback is off, or today's fallback allowance is used up (quota_exceeded: true), no calls come back.
Requests like these appear under Needs calls on the Retrain tab, ready to correct and train on. See Retrain.
My regenerated key doesn't work on the stable endpoint
Regenerate on the Overview replaces the live deployment's key, which works only with that deployment's versioned endpoint. The stable endpoint takes the project API key. See API keys and keyless calls.
Still stuck
Contact us with your project id, the utterance you sent, the call you expected and what came back. Never send your API key. See Support.
Revised