Troubleshooting

This page lists common problems with their causes and fixes. For the meaning of each error code, see Errors.

Requests fail

Every request returns 401

The Authorization header is missing or misspelled.
The key was copied with a character missing or changed.
The key expired or was revoked, or its project was deleted. Create a new key.
With MCP, the client does not send the header. Some clients need a restart after you change their configuration.

A request returns 400 with “Received unknown parameter”

The API refuses fields it does not know:

Scope fields are at the top level of a body. Put them inside "scope": { ... }.
A field is misspelled, such as occuredAt instead of occurred_at. Field names are snake_case.
A query parameter is not one the endpoint takes.

A request returns 400 about the time

The occurred_at time is in the future or before 1970. A common cause is a local time in a zone ahead of UTC sent without its offset, which Alvia reads as UTC. Send the offset, as in 2026-10-02T11:15:00+09:00, or convert to UTC first.

A request returns 415

The body was not sent as JSON. Set Content-Type: application/json.

A request returns 429

Read the body:

No reason. You are over your rate limit. Wait for the seconds in Retry-After, and slow down. All keys in your account share one limit. See Rate limits.
monthly_read_quota_reached or monthly_write_quota_reached. A monthly allowance is used up until resets_at. See Limits and allowances.

A write returns 409

The account holds its plan’s stored-memory limit. Forget memories you no longer need, or change plan.

Calls from a web page fail

The API serves server-side calls. Call Alvia from your server, which also keeps your key secret.

Memories are missing

A memory I just stored is not found

Formation runs after the write returns and finishes in less than a minute. Wait and read again. If it is still missing after a minute:

Check the scope. A read with a scope finds only memories written with matching values. Keep the user’s scope on application requests. Reproduce the miss with invented data in a test project, where a read without scope shows every memory; never broaden a customer request’s scope to diagnose it.
Check the project. The key you read with must belong to the project you wrote to.
Check the content. Text with no durable fact forms no memory. Small talk such as “thanks!” forms nothing.
Check for an existing memory. If Alvia already held the fact, it stored nothing new. Search for the existing memory.
Check the policy. Keyword or meaning exclusions can prevent a candidate from becoming memory. Test with invented data and an allowed positive control. See Filter memories.
Check date bounds. An old or revised memory can fall outside the range. See Filter by date.
Check your allowance. Formation forms facts up to the remaining write allowance. Check it in the dashboard.

Recall returns a different memory

Recall returns the best match for the query. Make the query more specific, add scope or use search to see the ranked candidates and their ranked_score.

A forgotten memory still appears in search

Forget removes the memory’s search entry during the request; if that step fails, Alvia finishes it in the background, and search and recall follow. Get, list and context drop the memory at once. Repeating the forget is safe; until search follows, filter the forgotten ID out in your application. See Forget a memory.

Answers are unexpected

Context returns an old fact

Check the dates. A fact sent without occurred_at is dated when you sent it, so an old fact sent late without its real date looks newer. See Point-in-Time Reasoning and change over time.
Check the scope. Formation compares a fact only with memories in the same scope. A change stored with a different scope does not replace the earlier fact.
Check the wording. Write a change as a change, as in “Atlas moved from PostgreSQL 16 to PostgreSQL 17”, so that Alvia relates it to the earlier fact.
Check the history. Inspect the memory, or open its History in the dashboard, to see how Alvia classified each fact, and why. A change classified as related or as a contradiction keeps the old memory current; forget the old memory if it no longer applies.

Context mentions two facts that disagree

Alvia classified the facts as a contradiction: they conflict, and neither replaces the other. The memory’s Relationships show the link. To settle it, forget the memory that no longer applies with DELETE /v1/memories/{memory_id}. Forgetting is permanent. See Forget a memory.

Context returns 404

Alvia has no context for this question right now, for example when no memory matches closely enough, and a later call can return one (see Get context). Check the scope and that the memories have formed, make the query more specific or use search to see what is stored.

Relative dates resolve to the wrong day

Alvia resolves “yesterday” and similar phrases on the calendar day of occurred_at, in the offset you sent. Send the user’s local time with its offset.

Report a problem

Collect the request’s method and path, the status, the full error body and the time, and report the problem to Alvia. Never include your API key.