velven
Docs
Menu

Troubleshooting

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

View as Markdown

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 Sync now on the space's edit page. To keep the board on server, post from your own function instead, as Server scores shows.

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.

Velven reads the block when the space is listed, on its background check every 6 hours, and when you press Sync now. Press Sync now in the Leaderboards section 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.

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.
  • The space is still processing. A new space stays Processing until its clip lands; see the clip is stuck on 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.

The proof tag 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 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 now 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 has every wait.

The clip is stuck on Processing

A new space stays Processing, 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 Processing. Fix it from the space's edit page:

  • Press Upload a clip to use a clip of your own. Its first frame becomes the thumbnail, and the space goes live at once.
  • Or press Retake, with a note on what the clip should show, such as "start after the title screen". You get 2 retakes per space.

An agent can ask for a retake too, with POST /api/spaces/recapture.