# Troubleshooting

Each heading is a symptom, and the first sentence under it is the usual cause. The fix follows.

## The safety check refused my version

The take of your version showed something the [content policy](https://velven.ai/content-policy) does not allow, or its address, or one its entry page names, is on a list of known malware and phishing. The reason is in the CLI's output and on the space's Files tab; the live version, if there is one, keeps serving.

- A sign-in, password, payment or wallet form is refused even in a game. Use [Sign in with Velven](https://velven.ai/docs/sdk/sign-in) for accounts.
- Betting for money, or anything that can be cashed out, is refused. Play money that never leaves the game is fine.
- If the reason is wrong, press Ask for review on the Files tab, once per version, and a person at Velven looks at it.

## The check could not judge my version

The take showed a black screen, a loading screen, or a start screen it never got past, so there was nothing to judge. What it saw is on the Files tab and in the CLI's output.

Add a `start` hint to `velven.json` and publish again: the check presses it before it looks. [velven.json](https://velven.ai/docs/hosting#velven-json) has the forms.

```json
{ "start": { "click": "Play" } }
{ "start": { "key": "Space" } }
{ "start": { "click": [640, 400] } }
```

A space that needs a long load, a sign-in or a second player to show anything can still be judged by a person: press Ask for review.

## Publishing answers too_large or too_many_files

A version holds at most 100 MB and 2,000 files, or 50 MB and 1,000 without an account; the message names the largest files. [Limits](https://velven.ai/docs/hosting#limits).

- Publish the build's output folder, not the project: `./dist`, `./build` or the export folder, never the folder with `node_modules` and sources.
- Leave source maps, raw assets and test files out with a `.velvenignore` file.
- Ship compressed builds: a `.br` or `.gz` file is served as the file inside it.

## velven publish --prod answers sign_in_required

You are not signed in, so the CLI publishes to an [unlisted page](https://velven.ai/docs/hosting#no-account), where every publish is checked and then live, and production needs an account. Run `velven login`, then publish again from the same folder: the page becomes yours and `--prod` works. In CI, set `VELVEN_TOKEN`.

## My hosted space is blank, or a file answers 404

A path in the page does not match a file in the version, usually because of a build setting.

- Paths are matched exactly, capitals included: `Assets/logo.png` is not `assets/logo.png`.
- The space has its own address, so paths from the root, such as `/assets/game.js`, work, and so do relative ones.
- A page that routes in the browser, with addresses like `/level/3`, needs `"spa": true` in `velven.json`.
- A build that needs `SharedArrayBuffer`, such as a threaded Godot 4 or Unity export, does not run on Velven. Export it without threads. [How Velven serves your files](https://velven.ai/docs/hosting#serving).

## Scores from a preview are not on the board

Previews and `velven dev` write to your space's [sandbox](https://velven.ai/docs/sdk/local#sandbox), never the live space, so what you test never shows publicly. `Velven.sandbox` is `true` there. Clear the test data with `velven reset`.

## Every score answers server_only

Your board's `trust` is `server`, the default, so Velven takes its scores only from your own server, never from the page.

For a page that posts its own scores, add `"trust":"client"` to the board in the page's block, deploy, and press Check my page now, under For developers on the Leaderboards tab of the space's edit page. To keep the board on `server`, post from your own function instead, as [Server scores](https://velven.ai/docs/sdk/server) shows. On a space Velven hosts, add it to the board in [`velven.json`](https://velven.ai/docs/hosting#velven-json) instead and publish a version that goes live.

```html
<script type="application/velven+json">
{"boards":[{"key":"main","trust":"client"}]}
</script>
```

> Note: On localhost the SDK takes a page's score on a `server` board, with a console note, so this shows up only on Velven. Add `?velven_strict=1` to the local address to see it there too.

## Scores answer no_board

Velven has no board with that key for your space, usually because it has not read the page's block since you added it.

On a space Velven hosts, Velven never reads the page's block: declare the board in [`velven.json`](https://velven.ai/docs/hosting#velven-json) and publish a version that goes live (`velven publish --prod`). A preview uses the live space's boards. The rest of this section is for a page on another host.

Velven reads the block when the space is listed, on its background check every 6 hours, and when you press Check my page now. The button is under For developers on the Leaderboards tab of the space's edit page; it says what it found. If the board is still missing, check these:

- The key in the call matches the block. A call that names no board uses `main`.
- The block is in the page's HTML as served, not added by a script after load.
- The block is valid JSON. On the first score call, the SDK warns in the console, once, when the page has no block or one that does not parse.

You can also write boards without a deploy, through the [REST API](https://velven.ai/docs/api#boards).

## Sign-in and scores answer unavailable

Sign-in and scores work only inside Velven, on a space that is published with a verified owner. Check each of these:

- The page is not inside Velven. On your own site, or in a frame elsewhere, `Velven.environment` is `site` and every sign-in and score call answers `unavailable`.
- The space is unclaimed. A space Velven listed itself answers `unavailable` until you [claim it](https://velven.ai/docs/quickstart#claim).
- The space is still processing. A new space stays Getting ready until its clip lands; see [the clip is stuck on Getting ready](https://velven.ai/docs/troubleshooting#processing).
- The space is off Velven, removed or refusing frames. The notice on its page says which.

## The proof check answers 409 unverified

Velven fetched your live page and did not find the proof tag naming your handle, usually because the deploy is not live yet or the host's cache still serves the old page.

Wait a minute, then check again. If it still fails, check these:

- The tag is in the page's HTML as served. Use View Source, not the browser's inspector: a tag added by a script after load does not count.
- The tag is in the `<head>` of the URL you listed, the page Velven lands on after redirects.
- `content` is your own handle, the one you are signed in as, such as `@mara`. Case does not matter.
- For a [move to another host](https://velven.ai/docs/hosting#move), the tag is on the new page, and on a claimed space it names the space's owner.

[The proof tag](https://velven.ai/docs/hosting#proof) has the steps for each host.

## Listing answers 422 unframeable

Your page's headers refuse to let velven.ai show it in a frame, with `X-Frame-Options` or a `Content-Security-Policy` whose `frame-ancestors` does not name velven.ai.

Every space plays inside the Velven page, so the fix is on your host. The answer's `instruction` and `snippet` name the change; [Allow Velven to frame your page](https://velven.ai/docs/hosting#framing) has it for each host. Deploy, then list the space again.

> Note: A listed space whose host starts refusing frames leaves Velven until the header is back. Its page and its edit page show you the fix and a Check again button, which puts it back as soon as the page allows framing.

## ready() takes 7 seconds outside Velven

In a frame that is not Velven's, such as another game portal or a blog, the SDK waits up to 7 seconds for Velven to answer before it settles on `site`.

Shorten the wait with `data-probe-timeout` on the script tag, or `probeTimeoutMs` in a bundle. The floor is 3 seconds, since inside Velven the page around your space can take that long to start on a slow phone.

```html
<script src="https://velven.ai/sdk/v1.js" data-probe-timeout="3000"></script>
```

In a top-level window and on localhost, `ready()` resolves at once. [Timing](https://velven.ai/docs/sdk/reference#reference-timing) has every wait.

## The clip is stuck on Getting ready

A new space stays Getting ready, visible only to you, until Velven has recorded its clip, which usually takes a few minutes.

If recording fails for good, the tile says Unable to capture the clip and the space stays Getting ready. Fix it on the Clip tab of the space's edit page:

- Press Choose a video to use a clip of your own. Its first frame becomes the thumbnail, and the space goes live at once.
- Or press Record again, with a note on what the clip should show, such as “start after the title screen”. You can ask 2 times per space.

An agent can ask for a retake too, with [`POST /api/spaces/recapture`](https://velven.ai/docs/agent#picture).