{
  "schemaVersion": "1.0",
  "canonical": "https://superlumin.al/docs/blender-addon/troubleshooting",
  "representations": {
    "html": "https://superlumin.al/docs/blender-addon/troubleshooting",
    "markdown": "https://superlumin.al/docs/blender-addon/troubleshooting.md",
    "json": "https://superlumin.al/docs/blender-addon/troubleshooting.json"
  },
  "retrievalHint": "Read page.description and page.relatedArticles first, then page.body. page.images lists every documentation screenshot with alt text, dimensions, captions, and annotations.",
  "page": {
    "path": "/docs/blender-addon/troubleshooting",
    "title": "Troubleshoot the Blender add-on",
    "description": "Diagnose connection, project, submission, dependency, render, and download problems without exposing credentials.",
    "navTitle": "Troubleshooting",
    "section": "Blender add-on",
    "sectionOrder": 20,
    "order": 8,
    "hidden": false,
    "keywords": [
      "Blender addon troubleshooting",
      "missing assets",
      "frame error",
      "upload failed",
      "stuck job",
      "crash",
      "hang",
      "not working",
      "job never appears"
    ],
    "updated": "2026-08-04",
    "body": "Start with the narrowest reproducible case: one saved scene, one representative frame, the same Blender and add-on versions, and a record of the exact time and organization.\n\n## Connection and projects\n\n**Browser connection opened but Blender stays disconnected**\n\n1. Confirm the browser flow reached its completed state.\n2. Return to the same Blender process and wait briefly.\n3. Retry **Connect to Superluminal** from the panel.\n4. Use the collapsed password form only as a fallback.\n\nThe connection flow itself is described in [Install and connect](/docs/blender-addon/install-and-connect#connect-to-superluminal).\n\n**Project picker is empty**\n\n- Confirm you are signed into the intended account and organization.\n- Create a project in the web app if none exists.\n- Use the refresh button beside the project picker.\n- If only one project is missing, confirm it belongs to the active organization.\n\n## Submission and upload\n\n**Submit buttons are disabled**\n\n- Save the `.blend` file.\n- Connect the account and select a valid project.\n- Check the image format. Video output disables submission. Use an image sequence.\n\n**PROJECT shows excluded or cross-drive dependencies**\n\n- Make the paths relative under a common project root.\n- Move or copy eligible assets beneath that root and relink them.\n- Choose a better custom root when the automatic root is too narrow.\n- Switch to ZIP when a self-contained package is the correct solution.\n\n**The terminal shows a red error panel**\n\nThe submission worker stops with the exact blocking paths listed. [Read the submission terminal](/docs/blender-addon/submission-terminal#when-something-goes-wrong) explains each stop and the diagnostic report it writes.\n\n![The submission terminal stopping on missing dependencies with the exact files listed](https://superlumin.al/docs/images/terminal/terminal-error.png)\n\n*A blocking trace error: the affected files are named relative to the project root.*\n\n**The external worker closes or the job never appears**\n\nThe worker registers the job only after tracing, packaging or synchronization, and upload all succeed. Save the worker's final error text, with any secrets redacted. Check network access and disk space. Then retry one frame as a ZIP submission. If that works, the problem is path mapping, not your account or the service.\n\n### Do not expose secrets\n\nRedact passwords, access tokens, session data, signed upload URLs, and credential-bearing request headers from screenshots or logs sent to anyone.\n\n## Render and frame errors\n\n1. Open the failed frame in the web job page.\n2. Inspect its logs and download the log file when available.\n3. Render the exact frame locally (not just frame 1) with the same Blender major/minor, engine, scene settings, view layer, and output.\n4. Check missing files, cache ranges, add-on runtime requirements, memory pressure, and output-node paths.\n5. If Blender wrote the full image before a repeatable cleanup crash, read about **Finish Frame On Error**. Do not enable it for an unexplained failure.\n6. Use **Re-render** only on the affected frame, and only after you correct or understand the cause.\n\n![The log view with search, match navigation, severity filter, and text-size controls](https://superlumin.al/docs/images/web/job-logs.png)\n\n*The job page's log view, scoped to the selected frame, with search and a severity filter.*\n\nIf persistent execution produces different output than an isolated local render, compare a short job with **Persistence Engine** disabled.\n\n## Wrong or incomplete image\n\n- Verify camera, frame, view layer, render layer, and scene selection.\n- Compare full downloaded output, not only the compressed web preview.\n- For multilayer EXR, choose the expected preview layer and inspect the original file in an EXR-aware application.\n- Check compositor file-output nodes for additional named outputs.\n- Confirm the selected image-format override did not replace the intended scene output.\n\n## Downloads\n\n**Interrupted download**\n\nRun **Download job output** again with the same job and folder. The downloader reconciles completed remote objects and existing local files.\n\n**No new frames arrive**\n\n- Confirm those frames are actually finished in the web app.\n- Leave the downloader running. It polls for newly finished frames.\n- Check whether the job is paused, blocked for funds, or errored.\n\n**A rerender is not reflected locally**\n\nRun the downloader again. It detects that the remote file changed and replaces the older local copy.\n\n## Information to collect\n\nWhen contacting support, include:\n\n- organization and project name\n- Job ID and the exact frame or range\n- Blender major/minor and add-on version\n- upload mode and any custom project root\n- image format, render pattern, and experimental settings\n- the event timestamp with timezone\n- a downloaded web log or redacted terminal error\n- short reproduction steps and what happened versus what you expected\n\n- [Support options](/docs/support): Use built-in chat, email, or Discord with a complete diagnostic packet.\n- [Dependencies](/docs/blender-addon/addons-and-dependencies): Audit files, caches, and add-ons before retrying.\n- [Web logs](/docs/web-ui/job-details#charts-and-logs): Search, filter, navigate, and download the current frame's logs.",
    "images": [
      {
        "id": "terminal-error",
        "src": "/docs/images/terminal/terminal-error.png",
        "alt": "The submission terminal stopping on missing dependencies with the exact files listed",
        "caption": "A blocking trace error: the affected files are named relative to the project root.",
        "width": 2232,
        "height": 1126,
        "annotations": []
      },
      {
        "id": "job-logs",
        "src": "/docs/images/web/job-logs.png",
        "alt": "The log view with search, match navigation, severity filter, and text-size controls",
        "caption": "The job page's log view, scoped to the selected frame, with search and a severity filter.",
        "width": 2880,
        "height": 620,
        "annotations": []
      }
    ],
    "machineReadable": {
      "markdown": "/docs/blender-addon/troubleshooting.md",
      "json": "/docs/blender-addon/troubleshooting.json"
    },
    "internalLinks": [
      "/docs/blender-addon/install-and-connect",
      "/docs/blender-addon/submission-terminal",
      "/docs/support",
      "/docs/blender-addon/addons-and-dependencies",
      "/docs/web-ui/job-details"
    ],
    "readingTime": "4 min read",
    "toc": [
      {
        "id": "connection-and-projects",
        "title": "Connection and projects",
        "level": 2
      },
      {
        "id": "submission-and-upload",
        "title": "Submission and upload",
        "level": 2
      },
      {
        "id": "do-not-expose-secrets",
        "title": "Do not expose secrets",
        "level": 3
      },
      {
        "id": "render-and-frame-errors",
        "title": "Render and frame errors",
        "level": 2
      },
      {
        "id": "wrong-or-incomplete-image",
        "title": "Wrong or incomplete image",
        "level": 2
      },
      {
        "id": "downloads",
        "title": "Downloads",
        "level": 2
      },
      {
        "id": "information-to-collect",
        "title": "Information to collect",
        "level": 2
      }
    ],
    "wordCount": 782,
    "relatedArticles": [
      {
        "path": "/compare/superluminal-vs-render-network",
        "title": "Superluminal vs Render Network",
        "description": "A recorded comparison of one completed Classroom job and two paid Junk Shop attempts, including credits, local output, and score."
      },
      {
        "path": "/compare/superluminal-vs-rebusfarm",
        "title": "Superluminal vs RebusFarm",
        "description": "RebusFarm used two tiers and RenderPoints. The comparison covers render-pipeline times, converted prices, upload, and delivery."
      },
      {
        "path": "/compare/superluminal-vs-fox-renderfarm",
        "title": "Superluminal vs Fox Renderfarm",
        "description": "Fox Renderfarm GPU 3 completed all four scenes. Recorded data covers farm time, local output, exact charges, Raysync, and EEVEE setup."
      }
    ]
  }
}