Skip to main content
Most GridOS errors fall into a small set of categories — provider configuration, rate limits, formula safety guards, and save/load issues. Use the accordions below to identify the error you’re seeing and apply the fix.
What it means: GridOS has no API key for any provider. The AI agent cannot run without at least one configured key.How to fix it:
  1. Click the gear icon in the GridOS menubar to open Settings.
  2. Paste an API key for at least one provider — Gemini is recommended.
  3. Save and close Settings.
  4. The model picker in the chat composer will now show available models. Send your prompt again.
Alternatively, create a .env file in the repository root with one of:
GOOGLE_API_KEY=your_key
ANTHROPIC_API_KEY=your_key
GROQ_API_KEY=your_key
OPENROUTER_API_KEY=your_key
…and restart the server.
What it means: The provider returned a 401 Unauthorized response. The key you configured is invalid, expired, belongs to a different product (e.g. a Google Cloud Vertex AI key pasted into the Gemini slot), or has trailing whitespace.How to fix it:
  1. Open Settings (gear icon).
  2. Find the provider whose key was rejected.
  3. Delete the existing key entry first — don’t just paste over it. Stale trailing characters are the single most common cause of persistent 401s.
  4. Copy a freshly-generated key from the provider’s console (click the copy button, don’t select-and-copy, which can grab whitespace).
  5. Paste and save. Retry your prompt.
A bad key for one provider does not affect other providers. If your Groq key is invalid but your Gemini key is valid, Gemini models continue working while you fix Groq.
Still seeing 401 with a freshly-pasted key? Check the Google / Anthropic / Groq console’s usage dashboard — if the key shows zero requests after you try in GridOS, the request isn’t reaching the provider at all (usually a typo). If you see requests there but GridOS still says rejected, the key was revoked/rotated and you need a new one.
What it means: The provider rejected the request because it would exceed the tokens-per-minute budget for the selected model on your current plan. Common on Groq’s free tier because reserved completion tokens count against the TPM bucket up-front — a 16K reservation on a 3.5K prompt “requests” ~19K tokens from the provider’s perspective, even though the model will only emit a few thousand.Typical message:
Error code: 413 — Request too large for model openai/gpt-oss-120b
... tokens per minute (TPM): Limit 8000, Requested 11749
How to fix it:
  1. Switch to a higher-TPM provider. Gemini Flash Lite has ~250K free-tier TPM — 30× what Groq free gives you. Pick it in the model picker and retry.
  2. Enable chain mode. In the chat composer, check the Chain toggle so the agent emits one rectangle per LLM call instead of packing the whole model into a single multi-intent response. This keeps each request well under any free-tier TPM cap.
  3. Upgrade the provider. Groq Dev Tier (~$5/mo) raises TPM caps substantially. Anthropic’s paid tier similarly.
  4. Wait 60 seconds. TPM is a rolling-minute bucket. Back-to-back failed attempts can double-count against the budget; a one-minute cooldown resets it.
See Which provider should I start with? for the full TPM table per provider.
What it means: The provider returned a transient error (gateway overload, upstream timeout). GridOS already retried the request four times with exponential backoff (~1s, ~2s, ~4s) before surfacing this error.How to fix it:Wait a moment, then send your prompt again. Transient overloads on Groq and OpenRouter free tiers are common during peak hours. If the error persists, switch to a different provider in the model picker — for example, switch from Groq to Gemini while Groq recovers.
What it means: The AI proposed one or more formulas that reference cells which are currently empty. Applying them would produce #DIV/0! errors or misleading zeros. GridOS blocks the write before it touches the sheet.The error message lists the affected cells and their empty references:
C4 (=DIVIDE(C3, B3)) references empty cell(s): C3, B3
How to fix it:
  • Re-ask the agent to include the inputs. “Fill in C3 and B3 with the baseline values first, then add the formula in C4.”
  • Fill the cells manually and re-send your original prompt.
  • Switch to multi-intent mode (the default on the agent). Multi-intent responses populate dependencies and formulas atomically in one call, so the guard sees all writes at once and doesn’t false-flag forward references.
What it means: The model either returned no content at all (usually hit its output-token cap with finish_reason=length) or returned prose that can’t be parsed as JSON. Common on smaller or older OSS models on complex prompts.How to fix it:
  • Switch to a stronger model. Gemini Flash Lite, Claude Haiku, or GPT-OSS 120B all handle structured output more reliably than tiny free-tier models.
  • Shorten the prompt. If you’re asking for a 3-statement model in one turn on a small model, split into smaller prompts (“build the income statement first, then the balance sheet”).
  • If finish_reason=length, the model ran out of output tokens. Either switch to chain mode (smaller responses per turn) or use a Groq model with a higher reservation (120B, 70B versatile).
What it means: The formula string in that cell could not be tokenized. The most common causes in agent-generated formulas used to be Excel-isms like $C$5 absolute refs or 15% percent literals — but GridOS now normalizes those automatically before parsing.What GridOS already handles transparently:
Excel-ismNormalized to
$C$5, $C5, C$5C5 (no fill-down semantics here, so $ is noise)
15%, 0.5%(15*0.01), (0.5*0.01)
Unicode −, ×, ÷, –, —ASCII -, *, /
What’s still unsupported:
  • Comparison operators in infix form (=A1 > 0): use the named form =GT(A1, 0) instead.
  • Cross-sheet references (=Sheet2!A1): on the roadmap.
  • Nested function calls in cells (=SUM(MAX(A1,B1), C1)): valid only inside macro bodies — see Formulas.
How to fix it:
  1. Open the cell in the formula editor.
  2. Look at the raw formula string. If it uses comparison operators or cross-sheet refs, rewrite with named functions or move the data to the active sheet.
  3. If you can’t spot the problem, re-ask the agent with a more constrained prompt (e.g. *“use MULTIPLY, not ”).
What it means: The formula called a function that isn’t in the registry — either a typo (=MULTIPLE vs =MULTIPLY) or an Excel-only function (=VLOOKUP).How to fix it:
#VALUE! — a function received the wrong number of arguments, or a non-numeric value where a number was required. Inspect the cell references to confirm they contain numeric data.#DIV/0! — DIVIDE was called with a zero denominator. Check that the denominator cell has a non-zero value. The pre-apply guard catches the most common form of this (empty denominator cell), but a cell that’s explicitly 0 still triggers it at calc time.
What it means: You clicked Load (or the server tried to auto-load on startup) but no system_state.gridos file exists. This happens on a fresh install or after the save file has been deleted.How to fix it: This is not an error — it simply means no previous session was saved. Start fresh by describing what you want to build in the chat, or open a preset template. Save your workbook after making changes using File → Save to create a save file for future loads.
What it means: The agent wrote a chart_spec but the chart didn’t render. The most common cause is that the data range referenced in the spec contains no data — the chart renderer has nothing to plot.How to fix it:
  1. Check that the cells in the data range actually contain values.
  2. If the cells are empty, ask the agent to populate the data first, then add the chart: “Fill A1:B6 with the revenue data, then add a bar chart.”
  3. If the data is present but the chart still doesn’t appear, ask the agent to re-create it by referring to it by name — GridOS upserts charts by title, so re-issuing the same spec updates the existing chart in place.

​
When to switch providers vs fix the prompt

Rough rule of thumb:
SymptomFix
401 / rejected keyRe-paste the key from provider console
413 TPM exceededSwitch provider or enable chain mode
422 empty-input formula guardRe-prompt to include dependencies
422 non-JSON outputSwitch to a stronger model
#NAME? in cellsTypo or unsupported function — see the primitives table
#PARSE_ERROR! in cellsFormula uses unsupported syntax (comparison infix, cross-sheet refs)
#VALUE!Wrong arg count or type — inspect references
#DIV/0!Denominator is literal zero — fix the input data