This page collects the support questions that come up most often and the fastest way to resolve each one. Every entry lists the symptom you observe, the cause behind it, and the fix to apply.

If your issue is not here, set `MEMWAL_MCP_DEBUG=1` for the Model Context Protocol (MCP) server, or, if you use the `withMemWal()` AI middleware, pass `debug: true` in its options, to get verbose logs, then open an issue on the repository with that output.

## How authentication works

Read this section first, because most authentication problems make sense once the model is clear. Walrus Memory does not use your owner wallet for day-to-day calls. Instead:

1. You generate a delegate key pair, an Ed25519 key, for example from the [Walrus Memory dashboard](https://memory.walrus.xyz).
2. The account owner registers the delegate public key onchain in your `MemWalAccount`. See [Delegate Key Management](/walrus-memory/contract/delegate-key-management).
3. The SDK or MCP client signs each request with the delegate private key.
4. On every request, the relayer verifies the signature, then looks up that public key in your account's onchain `delegate_keys` list to resolve the owner.

The key word is **registered**. A delegate key that exists locally but is not added to your account onchain, or is added to a different account, or is added on a different network, fails authentication. That single fact explains most `AUTH_REJECTED` reports.

Every signed request also carries a timestamp with a 5-minute validity window and a one-time nonce for replay protection, which is the second most common source of unexpected rejections.

## Authentication and delegate keys

This section covers credential and authorization errors.

### 401 `AUTH_REJECTED` errors

**Symptom:** You generated a delegate key, often from the dashboard, confirmed your account ID, and every authenticated call returns `AUTH_REJECTED` with HTTP status 401. A health check still succeeds, because the health endpoint needs no authentication, so the relayer is reachable but your signed requests are not accepted.

**Cause:** The relayer cannot match your signed request to an active, registered delegate key on the account you named. It verifies the Ed25519 signature, then resolves the owner by finding your public key in that account's onchain `delegate_keys`. Anything that breaks that lookup returns the same 401. The following causes are ordered by how often they apply to a freshly generated key, and each row pairs the check with its fix:

| **Cause** | **How to check** | **How to fix** |
| --- | --- | --- |
| The delegate key is not registered onchain yet, or its registration transaction is not indexed | Confirm the key appears under your account in the dashboard, and that any `addDelegateKey` call succeeded. | Register the public key onchain through the dashboard or `addDelegateKey`, then wait a few seconds for indexing and retry. |
| The account ID does not match the account that owns the key | Compare the `accountId` in your configuration against the account that lists this delegate key in the dashboard. A stale value in `localStorage` is a common source. | Use the account ID that you generated and that owns this delegate key, and do not reuse an account ID copied from another project. |
| The client points at a different network than the one where the account lives | Confirm your `serverUrl` or environment preset matches where you created the account. Production is `https://relayer.memory.walrus.xyz` and staging is `https://relayer-staging.memory.walrus.xyz`. | Point the client at the relayer for the correct network, or recreate the account and key in the environment you intend to use. |
| The system clock is outside the 5-minute signing window | Confirm the machine clock is accurate and synchronized using the Network Time Protocol (NTP). | Synchronize the clock and retry. |
| The delegate key is revoked, or the account is deactivated | Confirm the key is present and the account is active in the dashboard. | Re-add the delegate key, or reactivate the account, which only the owner can do. |

> **Tip**
>
> To triage quickly, confirm 3 things in order: the key is listed under the correct account in the dashboard, your account ID matches that account exactly, and your relayer environment matches where you created the account.
> **Info**
>
> A version mismatch is rarely the cause here. The relayer reports its minimum supported SDK version, which is TypeScript 0.0.4 at the time of writing, so 0.1.0 is supported. A true version mismatch surfaces as `MemWalCompatibilityError` rather than `AUTH_REJECTED`.
### Intermittent `isn't signed in` / `memwal_login` on recall

**Symptom:** The same credentials recall successfully one moment and fail the next with `Walrus Memory isn't signed in. Call the memwal_login tool, then retry.` `memwal_login` does not fix it. Other clients or a retry a few seconds later succeed.

**Cause:** The relayer re-checks the delegate key on Sui on every signed request. When Sui gRPC `GetObject` returns 429 or is otherwise unavailable, older relayers treated that as a revoked key, evicted the cache, and returned an empty HTTP 401. The SDK maps empty 401s to the login hint. The key is usually still registered.

**Fix:** Retry. This is not a sign-in failure. Current relayers keep the cached mapping when Sui cannot be consulted, or return HTTP 503 `upstream unavailable` on a cache miss. A 503 from the SDK means "retry"; it does not mean call `memwal_login`. If every call 401s, including after a few minutes, then follow the `AUTH_REJECTED` checks above.

## MCP Connection issues

This section covers problems that appear before the memory tools work.

### Only `memwal_login` appears

**Symptom:** After you connect the MCP server, the agent sees only `memwal_login`, or the memory tools return an authentication-required error.

**Cause:** No credentials file exists at `~/.memwal/credentials.json`. When an MCP host launches the package without credentials, it starts in an authentication-required mode. The tool list still advertises the core memory tools alongside `memwal_login`, but only `memwal_login` runs until you authenticate; the other tools return an authentication-required error when called, which is why it can look like `memwal_login` is the only tool available.

**Fix:** Ask the agent to call `memwal_login`, which returns a one-time sign-in URL valid for 5 minutes, or run `npx -y @mysten-incubation/memwal-mcp login --prod` in your terminal. Sign in to the wallet you intend to use before you open the URL. If the URL expires, call the tool again to get a fresh one.

### The MCP tools do not appear

**Symptom:** None of the `memwal_*` tools are available to the agent.

**Cause:** MCP servers load only when the client starts, so a server added during a session does not appear.

**Fix:** Quit the MCP client fully, then start it again. If you registered the server with `claude mcp add`, run `claude mcp list` to confirm `memwal` is registered before you restart.

### Sign-in succeeds but credentials are not saved

**Symptom:** The sign-in page confirms that your delegate key was registered, but says it could not hand the credentials back to your computer. The agent stays logged out and `~/.memwal/credentials.json` does not appear.

**Cause:** Signing in has two halves. Your browser registers a delegate key onchain, then sends that key back to a short-lived listener the MCP package runs on `127.0.0.1`. The key from this attempt is already on your account, and the MCP package saved its private half before it opened the sign-in page, so you can still use it. The usual reasons the hand-off fails:

- The MCP client restarted, or the login command was cancelled, while the browser tab was still open.
- This tab is leftover from a sign-in that already finished, or the hand-off did not match what the app expected.
- Local software such as a firewall, a VPN client, or a browser extension blocks requests from a website to `127.0.0.1`.

**Fix:** Restart your MCP client within 24 hours. On start, the MCP package finds the saved key, confirms it with the relayer, and signs you in with it, with no second wallet step. Do not call `memwal_login` first. It reuses the same key, and the wallet step fails because that key is already registered. Do not remove the key from the dashboard either, unless you mean to abandon it.

On Testnet the relayer cannot confirm the key at start, so the MCP package prints a notice instead of signing you in. Remove the key it names from the Delegate keys panel in the dashboard, then call `memwal_login` and open the new URL promptly.

MCP package versions before 0.0.13 do not save the key before the browser step. On those versions, remove the unused key from the dashboard and call `memwal_login` again.

If it keeps failing, confirm that nothing blocks localhost traffic, then run `npx -y @mysten-incubation/memwal-mcp login --prod` directly in a terminal. A terminal sign-in prints the failure reason instead of leaving it in the MCP client's logs.

## Saving and timeouts

This section covers slow or timed-out writes.

### `memwal_analyze` times out while recall works

**Symptom:** Recall returns quickly, but a save through `memwal_analyze` times out, sometimes on repeated attempts.

**Cause:** Recall is a single search request, so it is fast. A save is heavier, and `memwal_analyze` is the heaviest save: it runs a large language model (LLM) extraction over your text, then embeds and encrypts each extracted fact and enqueues each as its own background job that uploads to Walrus and indexes the result. Under load, this fan-out can exceed the MCP host's tool-call timeout even though the relayer keeps working normally.

> **Warning**
>
> A client-side timeout does not mean the save failed. The relayer accepts the work as background jobs and keeps processing after the client stops waiting. Running the same `memwal_analyze` call again can create duplicate memories, so confirm the result before you retry.
**Fix:**

1. Confirm the result instead of resubmitting. Wait a few seconds, because indexing can lag briefly under load, then run `memwal_recall` for the fact you tried to save. If the fact is present, the save succeeded despite the timeout.
2. Match the tool to the task. To save one discrete fact, such as a milestone, use `memwal_remember`, which performs a single write. Reserve `memwal_analyze` for longer passages where you want several facts extracted, and keep those passages a reasonable size.
3. Confirm connectivity first. Run `memwal_health`, which calls the unauthenticated health endpoint and is the fastest way to confirm the relayer is reachable.
4. Wait correctly in the SDK. The `remember` and `analyze` methods return immediately with job IDs, so wait with `waitForRememberJob` or `analyzeAndWait` and a sensible timeout, or poll the job status, rather than wrapping the whole operation in one short blocking call.
5. Collect logs if the problem persists. Set `MEMWAL_MCP_DEBUG=1` for the MCP server, or pass `debug: true` to the `withMemWal()` AI middleware, and capture the per-request output. The core SDK (`MemWal.create()`) has no built-in debug flag.

### Recall returns no results immediately after a save

**Symptom:** You save a memory, and an immediate recall finds nothing.

**Cause:** MCP `memwal_remember` returns at accept by default (`job_id`). The fact is not on Walrus yet, so recall has nothing to find. Even after the write lands, embedding/indexing can lag a few seconds under load.

**Fix:** Do not treat the accept reply as stored. Settle with `memwal_remember_status` (or wait until the tool returns a `blob_id`). Then retry recall. If a memory is missing from the search index later, `memwal_restore` rebuilds the index for that namespace from Walrus. `MEMWAL_MCP_REMEMBER_WAIT_MS=90000` restores wait-for-`blob_id` on a client that raises the 60s tools/call ceiling.

## Quick reference

Use these values for quick configuration and triage:

| **Item** | **Value** |
| --- | --- |
| Production relayer | `https://relayer.memory.walrus.xyz` |
| Staging relayer (Testnet) | `https://relayer-staging.memory.walrus.xyz` |
| Dashboard for accounts and delegate keys | `https://memory.walrus.xyz` |
| MCP environment presets | `--prod`, `--staging`, `--local` |
| Local credentials file | `~/.memwal/credentials.json` |
| Verbose MCP logs | `MEMWAL_MCP_DEBUG=1` |
| Unauthenticated health check | `memwal_health` |
| Maximum delegate keys per account | 20 |
| Request timestamp window | 5 minutes |

## Frequently asked questions

These answers are written for the product page.

### Is there a registration step after i generate a delegate key?

Yes. Generating a delegate key creates the key pair, and it works only after the owner registers its public key on your account onchain, which the dashboard does when you create the key there. The relayer checks for that registration on every request, so a key that is generated but not registered, or registered on a different account or network, fails authentication.

### Why do i get `AUTH_REJECTED` with a brand-new key?

The cause is almost always one of 3 things: the key is not registered on the account yet or is still settling, your account ID does not match the account that owns the key, or your client points at a different network than the one where you created the account. Check those in that order. A skewed system clock can also cause it, because each request carries a timestamp with a 5-minute window.

### Is my Testnet account the same as my production account?

No. Accounts and delegate keys are specific to each network. A key created on staging does not authenticate against the production relayer, and the reverse is also true. Confirm that your relayer environment matches where you created the account.

### My save timed out, so did i lose the memory?

Probably not. The relayer processes saves as background jobs and keeps working after the client times out. Do not save again right away, because that can duplicate the memory. Wait a few seconds and recall it to confirm. To save a single fact, use `memwal_remember` rather than `memwal_analyze`, which extracts and stores many facts at once and is the slowest operation.

### Why does recall feel instant while saving feels slow?

Recall is one search request. A save embeds, encrypts, uploads to Walrus, and indexes the result, and `memwal_analyze` does that for every fact it extracts. Saves are expected to take longer, and they run in the background.

### Score vs distance

SDK `recall` returns cosine **distance** (lower = more similar), and `maxDistance` drops hits where `distance >= maxDistance`. MCP `memwal_recall` prints **score** as `1 - distance` (higher = more similar). Do not apply an SDK `maxDistance` to MCP scores. That inverts the filter.

### How do i check whether the service is reachable?

Run `memwal_health`. It does not require authentication, so it separates the question of whether the relayer is reachable from whether your credentials are valid.