Sandbox Interface Not Found - The sandbox-interface.html…

Error message

Sandbox Interface Not Found - The sandbox-interface.html file could not be be found. Tried paths: ${localPath} ${docsPath}

What it means

HTTP 404 HTML page served by the sandbox server when sandbox-interface.html exists neither at the packaged local path nor at the fallback docs path. The message lists both tried locations, which tells you exactly where the server looked.

Solutions

Note the two tried paths in the error and check whether sandbox-interface.html exists anywhere in the package (find node_modules/<pkg> -name 'sandbox-interface.html')
Reinstall the package (npm install <pkg> --force or remove node_modules and reinstall) to restore missing assets
If running from a bundle, ensure __dirname resolves next to the shipped web assets or copy the file to one of the tried paths
Pin/upgrade to a version known to ship the file at one of those locations

Defensive patterns

Strategy: fallback

Validate before calling

null

Try / catch

try { await openSandboxUI(); } catch (e) { if (e.status === 404) promptReinstall('sandbox assets missing — reinstall the package'); }

Prevention

After install, verify web assets exist next to the server file
Pin package versions known to ship the UI
If bundling, ensure static assets are included relative to __dirname

When it happens

Trigger: GET of the sandbox UI route when both fs.existsSync checks fail — the HTML file was deleted, the package installation is incomplete/broken, or the file lives elsewhere (e.g. moved in a newer version).

Common situations: npm install of the package partially failed or node_modules was pruned; a version upgrade relocated sandbox-interface.html; running from a bundled/frozen executable where __dirname doesn't point at the shipped assets; someone deleted the analytics/sandbox web assets to save space.

Related errors

AI-assisted analysis of davila7/claude-code-templates@a0851ed10c (2026-08-28). Data as JSON: /api/errors/d32e693f2cb2376e. Report an issue: GitHub.

Appendix: source

Thrown at cli-tool/src/sandbox-server.js:101

// JSON parsing middleware
app.use(express.json());

// Store active tasks
const activeTasks = new Map();

// Serve the sandbox interface at root
app.get('/', (req, res) => {
    // Try local file first (when running from npm package)
    const localPath = path.join(__dirname, 'sandbox-interface.html');
    // Fallback to docs folder (when running from source)
    const docsPath = path.join(__dirname, '../../docs/sandbox-interface.html');
    
    if (fs.existsSync(localPath)) {
        res.sendFile(localPath);
    } else if (fs.existsSync(docsPath)) {
        res.sendFile(docsPath);
    } else {
        res.status(404).send(`
            <html>
                <body style="font-family: system-ui; padding: 40px; background: #0f0f0f; color: #e0e0e0;">
                    <h1>❌ Sandbox Interface Not Found</h1>
                    <p>The sandbox-interface.html file could not be found.</p>
                    <p>Please reinstall the package or check your installation.</p>
                    <pre style="background: #1a1a1a; padding: 10px; border-radius: 5px;">
Tried paths:
- ${localPath}
- ${docsPath}
                    </pre>
                </body>
            </html>
        `);
    }
});

// Serve static files for CSS, JS, etc. (but not index.html at root)
app.use('/css', express.static(path.join(__dirname, '../../docs/css')));

View on GitHub (pinned to a0851ed10c)