# Troubleshooting Guide
<subtitle>Diagnose model connection, script, asset, node, generation-task, and final-export problems by the stage where they occur.</subtitle>

First identify the stage where the problem occurs, then inspect its inputs and task details. Do not restart an entire episode because one stage failed.

```mermaid actions={false}
flowchart TD
    A["Problem occurs"] --> B{"Which stage?"}
    B -->|Sign-in or models| C["Check AstraFlow Key and available models"]
    B -->|Canvas or script creation| D["Check content language, file format, and size"]
    B -->|Assets or storyboard| E["Check processing status, descriptions, and references"]
    B -->|Infinite Canvas| F["Check node inputs, connections, and task status"]
    B -->|Video or export| G["Open Task Queue details"]
    C --> H{"Working again?"}
    D --> H
    E --> H
    F --> H
    G --> H
    H -->|No| I["Record page, task type, and error summary"]
    H -->|Yes| J["Continue the current step"]
```

## No Models After Connecting AstraFlow

1. Confirm that you entered a currently valid AstraFlow API Key.
2. Confirm that the Key has no extra spaces and is not exposed in a screenshot or public text.
3. Reopen Director Console settings and check whether model options load.
4. If a previously configured model is now unavailable, select one currently offered by the interface.

## Script Cannot Be Uploaded

- The file extension must be `.txt`.
- The file must contain content.
- The file must not exceed 500 KB.
- If the file still cannot be used, open it, copy the content, and use **Paste Text**.

## Wrong Content Language

The content language cannot be changed after creation. Create a new canvas with the correct language and import the script again. Changing the interface language does not change the creative content language.

## Script Processing Failed or Stopped Progressing

1. Check the current stage shown on the script card.
2. Open the Task Queue and find the corresponding failed or interrupted task.
3. Read the error summary and determine whether it concerns the model, input, or network.
4. Retry only the failed step indicated by the page.

## Asset Cannot Be Edited

If the page indicates that script or continuity processing is still running, wait for the current step to finish. The interface remains read-only because a forced change would conflict with the background result.

## Asset Images or Storyboard Direction Are Inconsistent

1. Check the asset name and description and confirm that the shot references the correct variant.
2. Regenerate a still frame for one representative shot.
3. If the result remains unsatisfactory, refine the asset on the Infinite Canvas and preferably add it as a new variant.
4. After confirming the direction, batch-process the other affected content.

## Canvas Node Cannot Generate

- Check whether the selected model is still available.
- Check whether required text or reference images are empty.
- Check whether upstream connections provide input types supported by the target node.
- Check the Task Queue for duplicate queued or running tasks.
- Open the failed task, correct the input, and resubmit.

## Canvas Media Upload Failed

- Text: `.txt`, up to 1 MB.
- Images: `.jpg`, `.jpeg`, `.png`, `.gif`, or `.webp`, up to 10 MB.
- Video: `.mp4`, `.webm`, or `.mov`, up to 50 MB.
- Audio: `.mp3` or `.wav`, up to 30 MB.
- Confirm that the file extension matches the actual media type. The server does not currently accept `.md` or `.ogg`.

## Canvas Media Does Not Appear in the Editor

Confirm that media generation or upload has completed and that the correct script, scene group, and shot are selected in the Editor. Then reopen the Canvas Media category.

## Video Generation Failed

1. Open task details and inspect the model and error summary.
2. Check the shot description, still frame, and reference media.
3. Confirm that the current model supports the selected input method.
4. Correct the problem and retry only that shot.

## Merge & Export Failed

1. Open the Final Video Export task details.
2. Confirm that timeline media can still be previewed.
3. Fix unintended gaps, overlaps, or inaccessible media clips.
4. Confirm visual and audio track states, then export again.

## Information to Prepare When Reporting a Problem

- The page and sequence of actions where it occurred.
- The current canvas, script, and shot location, without including an API Key.
- Task type, status, and error summary.
- The time of occurrence and whether the problem can be reproduced consistently.
- An interface screenshot with account information hidden.

## Related Pages

- [Connect AstraFlow](/docs/bomitv/getting-started/astraflow.md)
- [Task Queue](/docs/bomitv/reference/tasks.md)
- [Frequently Asked Questions](/docs/bomitv/help/faq.md)