English

FAQ & Troubleshooting

Help: Quick Start · Stories · Characters · Lore Books · Multiplayer · Discover · Advanced · Templates · FAQ

This page covers the most common problems and how to resolve them.

The AI isn't generating anything

Symptoms: You press Continue or send a message, but no AI response appears. The generation spinner runs indefinitely or nothing happens at all.

Things to check:

  1. Model configuration — go to Config → Models (admin) and confirm a model is configured. Check that the API URL is correct and reachable from the server. If the model is a cloud provider, confirm the API key is valid and has not expired or been revoked.
  2. At least one eligible AI character — the AI only generates for characters that are present, not muted, and not currently incarnated by a user. If every character in the story is either muted or incarnated, there is nobody for the AI to speak as. Open the Characters tab in the config panel and check the toggles.
  3. API key validity — if you recently rotated your API key, update it in Config → Models. The old key field is masked after saving, so you may need to re-enter the key even if the field appears filled.
  4. Server logs — if you have server access, check the application logs for error messages from the generation job. These often pinpoint the exact API error (e.g. rate limits, model not found, context too long).

Lore entries aren't triggering

Symptoms: You expect a lore entry to appear in the prompt based on its tags, but the AI seems unaware of the relevant lore.

Things to check:

  1. Tag matching — lore tags trigger when the exact word or substring appears in recent message history. The match is case-insensitive but otherwise literal. If your tag is Aria but recent messages say she or the elf, the tag will not match. Try broader or more common terms.
  2. Test with Permanent — temporarily mark the entry as Permanent to force it into every prompt. If the AI suddenly knows the lore, the issue is tag matching. If not, the entry may be getting cut by the budget.
  3. Lore context budget — open the story's Context settings and increase the Lore Context Length. If many entries are competing, lower-weight ones may be cut entirely. Increase the weight of critical entries or remove lower-priority ones.
  4. Lore book not attached — confirm the lore book is attached to the story. Open the Lore tab in the play screen config panel and check whether the book appears in the attached list.

The AI keeps writing the same character

Symptoms: In a story with multiple AI characters, one character dominates every response and the others rarely or never speak.

Things to check:

  1. Chativity values — open each character's settings and review their Chativity value (0–1). If one character has a much higher chativity than the others, it will win the spontaneous-speech lottery more often. Lower the dominant character's chativity or raise the others.
  2. Muted characters — check the Characters tab in the config panel. If some characters are accidentally muted, they will never speak. Toggle Muted off for the characters you want the AI to play.
  3. Presence — confirm all intended characters have Presence enabled. A character with Presence off is excluded from the prompt entirely and will never generate.
  4. Final instructions in the System Prompt — if your System Prompt template explicitly instructs the AI to continue as a specific character by name (e.g. near the closing instructions after the message history block), it will always follow that instruction. Review the end of your System Prompt in your preset or story settings.

Generation is very slow

Symptoms: The AI takes a long time to produce each response.

Things to understand: Generation speed depends primarily on the model and provider, not on Dream Scrolls itself.

  • Cloud providers (OpenAI, Mistral, etc.) — speed depends on the provider's current load and the model tier. Larger models (e.g. GPT-4 class) are slower than smaller ones.
  • Self-hosted models (Ollama, Llama.cpp, VLLM) — speed depends directly on your hardware. CPU-only inference is significantly slower than GPU inference. Quantized models (e.g. Q4_K_M) are faster than full-precision models at some quality cost.

Things to try:

  • Switch to a smaller model or a faster model tier in Config → Models and update the story's model in the Model tab.
  • Reduce Max New Tokens in the generation settings — shorter responses generate faster.
  • Reduce Context Length if it is very high — a longer context takes more time to process.
  • If using a self-hosted model, check GPU utilisation on the server. Ensure the model is loaded into VRAM rather than running in RAM.

Context fills up too fast

Symptoms: The message history is truncating early, old messages are missing, or generation quality degrades because the model cannot see enough history.

Things to try:

  1. Enable Summarization — this is the primary solution for long stories. See Advanced for full configuration details. Summarization compresses old messages into concise summaries, freeing up tokens for new content.
  2. Reduce permanent lore entries — permanent entries consume lore context on every generation regardless of relevance. Review your lore books and convert non-essential permanent entries to tag-triggered ones.
  3. Lower Lore Context Length — if lore is consuming a large share of your total context budget, reducing this value leaves more room for message history.
  4. Shorten character descriptions — long, detailed character descriptions are injected on every generation. Trim them to the essential traits and move backstory detail into lore entries that only trigger when relevant.
  5. Increase total Context Length — if your model supports a larger context window than your current setting, increase the Context Length in the story's Context settings.

Import fails with a 413 error

Symptoms: Uploading a .scenario.zip, a CharacterCard PNG, or a lore book JSON fails with an HTTP 413 (Request Entity Too Large) error.

Cause: The uploaded file exceeds the server's maximum allowed request body size.

Resolution: Ask your server administrator to increase the HTTP_BODY_LIMIT environment variable in the server configuration (.env). After restarting the server, the larger file size will be accepted.

If you are the administrator, refer to the deployment documentation for how to set environment variables for the Dream Scrolls backend.

Characters aren't visible in my story

Symptoms: You created characters, but they do not appear in the story's Characters tab or in the message feed.

Things to check:

  1. Character not attached to the story — characters must be explicitly attached to a story. In the story settings (edit form or the Story tab in the play screen), look for the character attachment section and add the characters you want.
  2. Presence is disabled — a character can be attached but have Default Present disabled, meaning they are in the cast but inactive. Open the Characters tab in the play screen config panel and toggle Presence on for the relevant characters.
  3. Wrong story — confirm you are in the correct story. Multiple stories can share the same characters, and each story has its own character attachment list.

I can't send messages

Symptoms: The message input is disabled or greyed out, and pressing Enter does nothing.

Cause: You need to incarnate a character before you can send messages. Dream Scrolls requires you to explicitly take control of a character so that your messages are correctly attributed.

Resolution:

  1. Open the config panel and go to the Characters tab.
  2. Find the character you want to speak as.
  3. Click Voice to incarnate it.
  4. The message input will become active.

If the Voice button is disabled, another user is already incarnating that character. Choose a different character or wait for the other user to release control.

Vector search isn't working

Symptoms: You expected lore entries to be retrieved by semantic similarity, but they are not appearing in the prompt even when the content is clearly relevant.

Things to check:

  1. Embedding model not assigned — open the lore book settings and confirm an embedding-capable model is selected in the Embedding Model field. If no embedding models appear in the dropdown, an admin needs to add one under Config → Models with Embedding Capable enabled.
  2. Re-vectorize not run — after assigning an embedding model, you must click Re-vectorize to generate embeddings for all existing entries. New entries added after the last Re-vectorize run will also need to be re-vectorized.
  3. Vectorization Threshold too high — the Vectorization Threshold (0–1) sets the minimum similarity score for inclusion. If it is set close to 1.0, only near-identical matches will qualify. Try lowering it to 0.6–0.75 to see if more entries are retrieved.
  4. Lore context budget exhausted — even if vector search retrieves entries, they may be cut if the lore context budget is full. Check the Lore Context Length in the story's Context settings.

I lost my story after playing as a guest

Symptoms: You played a story as a Guest (without logging in), then closed the browser or your session expired, and the story is gone.

Cause: Guest (anonymous) sessions are not persisted. Stories, characters, and messages created during a guest session exist only in the browser session and are not saved to the server.

Resolution: Create a registered account to save your work permanently. With a User account, all stories, characters, and lore books are saved to your profile and persist across sessions and devices.

If you instantiated a public scenario as a Guest, you can do so again at any time — the original scenario is always available in Discover.