> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/stormkit-io/stormkit-io/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment Troubleshooting

> Solutions to common deployment issues, build failures, and configuration problems in Stormkit.

## Common Issues

This guide helps you resolve the most common deployment problems on Stormkit.

## Top-level /index.html Missing

### Problem

You see a warning: "Top-level /index.html missing" in your deployment logs.

### What It Means

Stormkit cannot find an `index.html` file at the root of your deployed files, and server-side rendering is not detected.

### Important Note

<Note>
  This warning doesn't necessarily mean your deployment failed. It just means your root path (`/`) will return 404. Other uploaded files will still be accessible.
</Note>

### Diagnosis Steps

<Steps>
  <Step title="Check Deployment Manifest">
    1. Find your deployment in the **Deployments** list
    2. Expand the menu (**...**)
    3. Click **Manifest**
    4. Review **CDN Files** section
  </Step>

  <Step title="Verify File Structure">
    Check if `index.html` is listed in the CDN files. If not, it wasn't included in the build output.
  </Step>
</Steps>

### Solutions

#### Solution 1: Fix Output Folder

Your build may be outputting to the wrong directory.

<Steps>
  <Step title="Check Build Output">
    Verify where your build tool outputs files:

    * Vite: Usually `dist/`
    * Create React App: Usually `build/`
    * Next.js: Usually `out/` (static export)
    * Gatsby: Usually `public/`
  </Step>

  <Step title="Update Configuration">
    Go to **Environment** > **Config** > **Output folder** and set the correct path
  </Step>

  <Step title="Redeploy">
    Trigger a new deployment to test the fix
  </Step>
</Steps>

#### Solution 2: Enable Server-Side Rendering

If you need a dynamic application, enable SSR:

<Tabs>
  <Tab title="Nuxt.js">
    Stormkit automatically detects Nuxt.js SSR applications. Ensure your build outputs a `.stormkit/server` folder.
  </Tab>

  <Tab title="Next.js">
    Stormkit supports static exports for Next.js. For SSR, contact support about framework adapters.
  </Tab>

  <Tab title="Custom Framework">
    Create a `.stormkit/server` folder with a server entry file:

    ```javascript .stormkit/server/server.js theme={null}
    export const handler = ({ req, res }) => {
      res.write('hello world')
      res.end()
    }
    ```

    You'll need a bundler like Vite or Webpack to bundle your app to this location.
  </Tab>
</Tabs>

### How SSR Changes Routing

* **SSR disabled**: Requests must match exact file paths (e.g., `/about.html`)
* **SSR enabled**: All non-CDN requests forward to serverless handler

## Repository is Inaccessible

### Problem

Error: "Repository is inaccessible" or "Stormkit has no access to the repo"

### Causes

1. Repository URL changed
2. Git provider credentials expired
3. Repository was deleted or made private
4. OAuth app was revoked

### Solution: Update Repository URL

<Steps>
  <Step title="Navigate to Settings">
    Go to **Your Application** > **Settings**
  </Step>

  <Step title="Update Repository URL">
    Paste the HTTPS URL of your repository

    ```
    https://github.com/username/repository
    ```
  </Step>

  <Step title="Test Connection">
    Try deploying to verify access
  </Step>
</Steps>

### Solution: Refresh GitHub Access

<Steps>
  <Step title="Open GitHub Integration">
    1. Visit [app.stormkit.io](https://app.stormkit.io)
    2. Click **Create new app**
  </Step>

  <Step title="Connect More Repositories">
    Click **Connect more repositories**
  </Step>

  <Step title="Grant Access">
    In the popup, grant access to the repository
  </Step>

  <Step title="Test Deployment">
    Close the popup and try deploying again
  </Step>
</Steps>

### Solution: Refresh GitLab Access

<Steps>
  <Step title="Revoke Old Tokens">
    1. Visit [gitlab.com](https://gitlab.com)
    2. Click **Avatar** > **Preferences** > **Applications**
    3. Revoke any Stormkit-related tokens
  </Step>

  <Step title="Re-authorize">
    1. Visit [app.stormkit.io](https://app.stormkit.io)
    2. Log in with GitLab
    3. Accept authorization prompt
  </Step>

  <Step title="Test Deployment">
    Try deploying your application
  </Step>
</Steps>

### Solution: Check Repository Permissions

For organization repositories:

* Verify Stormkit GitHub App has access to the organization
* Check if repository is private and Stormkit has permission
* Ensure you're logged in with the correct Git provider account

## Branch Does Not Exist

### Problem

Error: "Stormkit has no access to the repo or the branch does not exist"

### Causes

1. Branch was deleted from repository
2. Branch name was misspelled in configuration
3. Repository access issue (see above)

### Solutions

<Steps>
  <Step title="Verify Branch Exists">
    Check your Git repository to confirm the branch exists:

    ```bash theme={null}
    git branch -r
    ```
  </Step>

  <Step title="Update Environment Config">
    1. Go to **Environment** > **Config**
    2. Update **Branch** setting to an existing branch
    3. Save changes
  </Step>

  <Step title="Test Deployment">
    Try deploying the updated branch
  </Step>
</Steps>

If the branch exists and you still see this error, follow the [Repository is Inaccessible](#repository-is-inaccessible) steps.

## Cannot Find My App

### Problem

Your application is missing from the dashboard.

### Cause

You logged in with a different provider than when you created the app. Each provider creates a separate account if emails differ.

### Example

* Created app while logged in with **GitHub** ([github@example.com](mailto:github@example.com))
* Now logged in with **GitLab** ([gitlab@example.com](mailto:gitlab@example.com))
* Apps are in different accounts

### Solutions

#### Option 1: Use Original Provider

<Steps>
  <Step title="Log Out">
    Sign out of Stormkit
  </Step>

  <Step title="Log In with Correct Provider">
    Sign in using the provider you originally used to create the app
  </Step>
</Steps>

#### Option 2: Migrate Apps

If you need to migrate apps between accounts:

* Contact support via [Discord](https://discord.gg/6yQWhyY)
* Or email: [hello@stormkit.io](mailto:hello@stormkit.io)

Provide:

* Current account email/provider
* Target account email/provider
* App IDs to migrate

## Build Failures

### Node.js Version Mismatch

#### Problem

Build fails with Node.js version errors:

```
Error: The engine "node" is incompatible with this module
```

#### Solution

Specify Node.js version:

<CodeGroup>
  ```bash .node-version theme={null}
  20.11.0
  ```

  ```toml mise.toml theme={null}
  [tools]
  node = "20.11.0"
  ```

  ```json package.json theme={null}
  {
    "engines": {
      "node": ">=20.0.0"
    }
  }
  ```
</CodeGroup>

### Out of Memory

#### Problem

Build fails with:

```
JavaScript heap out of memory
```

#### Solution

Increase Node.js memory:

```json package.json theme={null}
{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' vite build"
  }
}
```

Or in environment config:

**Build command**: `NODE_OPTIONS='--max-old-space-size=4096' npm run build`

### Missing Dependencies

#### Problem

```
Error: Cannot find module 'some-package'
```

#### Solutions

<AccordionGroup>
  <Accordion title="Ensure dependencies are in package.json">
    ```bash theme={null}
    npm install some-package --save
    ```

    Commit updated `package.json` and `package-lock.json`
  </Accordion>

  <Accordion title="Check if dependency is in devDependencies">
    If used during build, move to `dependencies`:

    ```bash theme={null}
    npm install some-package --save-prod
    ```
  </Accordion>

  <Accordion title="Clear npm cache">
    Sometimes cached dependencies cause issues. In build command:

    ```bash theme={null}
    npm ci --cache .npm
    ```
  </Accordion>
</AccordionGroup>

### Build Command Not Found

#### Problem

```
npm ERR! missing script: build
```

#### Solution

Add build script to `package.json`:

```json package.json theme={null}
{
  "scripts": {
    "build": "vite build"
  }
}
```

Or update environment config **Build command** to match your actual script.

## Deployment Timeout

### Problem

Deployment times out or takes too long.

### Solutions

<Steps>
  <Step title="Optimize Build">
    * Remove unnecessary build steps
    * Use build caching where possible
    * Reduce asset size (images, fonts)
  </Step>

  <Step title="Check External Services">
    If build calls external APIs:

    * Add timeouts to API calls
    * Use build-time data caching
    * Consider moving API calls to runtime
  </Step>

  <Step title="Review Dependencies">
    * Audit large dependencies
    * Use lighter alternatives
    * Remove unused packages
  </Step>
</Steps>

## Environment Variables Not Working

### Problem

Environment variables are `undefined` at runtime or build time.

### Diagnosis

<AccordionGroup>
  <Accordion title="Check variable is set">
    Verify in **Environment** > **Config** > **Environment Variables**
  </Accordion>

  <Accordion title="Check variable name">
    Variable names are case-sensitive:

    * `API_KEY` ≠ `api_key`
  </Accordion>

  <Accordion title="Check framework requirements">
    Some frameworks require prefixes:

    * **Next.js**: `NEXT_PUBLIC_` for browser
    * **Vite**: `VITE_` for browser
    * **Create React App**: `REACT_APP_` for browser
  </Accordion>

  <Accordion title="Rebuild required">
    Environment variables are injected at build time. After changing variables, trigger a new deployment.
  </Accordion>
</AccordionGroup>

### Solution Examples

<Tabs>
  <Tab title="Next.js">
    ```javascript theme={null}
    // ✅ Server-side (works without prefix)
    const secret = process.env.API_SECRET

    // ✅ Client-side (needs NEXT_PUBLIC_ prefix)
    const publicKey = process.env.NEXT_PUBLIC_API_KEY
    ```
  </Tab>

  <Tab title="Vite">
    ```javascript theme={null}
    // ✅ Client-side (needs VITE_ prefix)
    const apiUrl = import.meta.env.VITE_API_URL

    // ❌ Won't work (no prefix)
    const wrong = import.meta.env.API_URL
    ```
  </Tab>

  <Tab title="Node.js/API">
    ```javascript theme={null}
    // ✅ Server-side (no prefix needed)
    const dbUrl = process.env.DATABASE_URL
    const apiKey = process.env.API_KEY
    ```
  </Tab>
</Tabs>

## Assets Not Loading (404s)

### Problem

CSS, JavaScript, or images return 404 errors.

### Causes & Solutions

<AccordionGroup>
  <Accordion title="Incorrect base path">
    Set correct base URL in build tool:

    ```javascript vite.config.js theme={null}
    export default defineConfig({
      base: '/',  // or '/subdirectory/'
    })
    ```
  </Accordion>

  <Accordion title="Absolute paths in development">
    Use relative paths or environment-aware URLs:

    ```html theme={null}
    <!-- ❌ Bad -->
    <img src="http://localhost:3000/logo.png" />

    <!-- ✅ Good -->
    <img src="/logo.png" />
    ```
  </Accordion>

  <Accordion title="Assets not copied">
    Ensure build process copies static assets:

    ```javascript vite.config.js theme={null}
    export default defineConfig({
      publicDir: 'public',  // Assets to copy
    })
    ```
  </Accordion>
</AccordionGroup>

## Serverless Function Errors

### Problem

API routes or SSR functions return errors.

### Common Issues

<AccordionGroup>
  <Accordion title="Missing handler export">
    Ensure your function exports correctly:

    ```javascript theme={null}
    // ✅ Correct
    export default async (req, res) => {
      res.end('OK')
    }

    // ❌ Wrong
    module.exports = async (req, res) => {
      res.end('OK')
    }
    ```
  </Accordion>

  <Accordion title="Missing dependencies">
    Include dependencies in deployment:

    * Check `package.json` includes all deps
    * Verify `node_modules` in `.stormkit/api` or `.stormkit/server`
  </Accordion>

  <Accordion title="Timeout">
    Functions have execution time limits. Optimize slow operations:

    * Add database query optimization
    * Implement caching
    * Use async operations efficiently
  </Accordion>

  <Accordion title="Cold start">
    First request may be slow. Minimize cold starts:

    * Keep dependencies lean
    * Lazy load heavy modules
    * Use connection pooling for databases
  </Accordion>
</AccordionGroup>

## Getting Help

If you're still experiencing issues:

### Check Logs

1. Go to your deployment
2. Click **View Logs**
3. Look for error messages and stack traces

### Community Support

Join the Stormkit Discord:

* [Discord Server](https://discord.gg/6yQWhyY)
* Ask in `#support` channel
* Share deployment logs and error messages

### Contact Support

For urgent issues:

* Email: [hello@stormkit.io](mailto:hello@stormkit.io)
* Include:
  * App ID
  * Deployment ID
  * Error messages
  * Steps to reproduce

## Related Documentation

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/deployments/configuration">
    Configure build and deployment settings
  </Card>

  <Card title="How We Deploy" icon="diagram-project" href="/deployments/how-we-deploy">
    Understand deployment process
  </Card>

  <Card title="System Variables" icon="code" href="/deployments/system-variables">
    Environment variables reference
  </Card>

  <Card title="Application Runtime" icon="server" href="/deployments/application-runtime">
    Server application configuration
  </Card>
</CardGroup>