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

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.

Diagnosis Steps

1. Check Deployment Manifest

   1. Find your deployment in the Deployments list
   2. Expand the menu (…)
   3. Click Manifest
   4. Review CDN Files section
2. Verify File Structure

   Check if index.html is listed in the CDN files. If not, it wasn’t included in the build output.

Solutions

Solution 1: Fix Output Folder

Your build may be outputting to the wrong directory.

1. 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/
2. Update Configuration

   Go to Environment > Config > Output folder and set the correct path

3. Redeploy

   Trigger a new deployment to test the fix

Solution 2: Enable Server-Side Rendering

If you need a dynamic application, enable SSR:

Nuxt.js

Stormkit automatically detects Nuxt.js SSR applications. Ensure your build outputs a .stormkit/server folder.

Next.js

Stormkit supports static exports for Next.js. For SSR, contact support about framework adapters.

Custom Framework

Create a .stormkit/server folder with a server entry file:

.stormkit/server/server.js

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.

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

1. Navigate to Settings

   Go to Your Application > Settings

2. Update Repository URL

   Paste the HTTPS URL of your repository

   https://github.com/username/repository
   
3. Test Connection

   Try deploying to verify access

Solution: Refresh GitHub Access

1. Open GitHub Integration

   1. Visit app.stormkit.io
   2. Click Create new app
2. Connect More Repositories

   Click Connect more repositories

3. Grant Access

   In the popup, grant access to the repository

4. Test Deployment

   Close the popup and try deploying again

Solution: Refresh GitLab Access

1. Revoke Old Tokens

   1. Visit gitlab.com
   2. Click Avatar > Preferences > Applications
   3. Revoke any Stormkit-related tokens
2. Re-authorize

   1. Visit app.stormkit.io
   2. Log in with GitLab
   3. Accept authorization prompt
3. Test Deployment

   Try deploying your application

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

1. Verify Branch Exists

   Check your Git repository to confirm the branch exists:

   git branch -r
   
2. Update Environment Config

   1. Go to Environment > Config
   2. Update Branch setting to an existing branch
   3. Save changes
3. Test Deployment

   Try deploying the updated branch

If the branch exists and you still see this error, follow the 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 ([e-mail])
• Now logged in with GitLab ([e-mail])
• Apps are in different accounts

Solutions

Option 1: Use Original Provider

1. Log Out

   Sign out of Stormkit

2. Log In with Correct Provider

   Sign in using the provider you originally used to create the app

Option 2: Migrate Apps

If you need to migrate apps between accounts:

• Contact support via Discord
• Or email: [e-mail]

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:

.node-version

20.11.0

Out of Memory

Problem

Build fails with:

JavaScript heap out of memory

Solution

Increase Node.js memory:

package.json

{
  "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

Ensure dependencies are in package.json

npm install some-package --save

Commit updated package.json and package-lock.json

Check if dependency is in devDependencies

If used during build, move to dependencies:

npm install some-package --save-prod

Clear npm cache

Sometimes cached dependencies cause issues. In build command:

npm ci --cache .npm

Build Command Not Found

Problem

npm ERR! missing script: build

Solution

Add build script to package.json:

package.json

{
  "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

1. Optimize Build

   • Remove unnecessary build steps
   • Use build caching where possible
   • Reduce asset size (images, fonts)
2. Check External Services

   If build calls external APIs:

   • Add timeouts to API calls
   • Use build-time data caching
   • Consider moving API calls to runtime
3. Review Dependencies

   • Audit large dependencies
   • Use lighter alternatives
   • Remove unused packages

Environment Variables Not Working

Problem

Environment variables are undefined at runtime or build time.

Diagnosis

Check variable is set

Verify in Environment > Config > Environment Variables

Check variable name

Variable names are case-sensitive:

• API_KEY ≠ api_key

Check framework requirements

Some frameworks require prefixes:

• Next.js: NEXT_PUBLIC_ for browser
• Vite: VITE_ for browser
• Create React App: REACT_APP_ for browser

Rebuild required

Environment variables are injected at build time. After changing variables, trigger a new deployment.

Solution Examples

Next.js

// ✅ 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

Vite

// ✅ 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

Node.js/API

// ✅ Server-side (no prefix needed)
const dbUrl = process.env.DATABASE_URL
const apiKey = process.env.API_KEY

Assets Not Loading (404s)

Problem

CSS, JavaScript, or images return 404 errors.

Causes & Solutions

Incorrect base path

Set correct base URL in build tool:

vite.config.js

export default defineConfig({
  base: '/',  // or '/subdirectory/'
})

Absolute paths in development

Use relative paths or environment-aware URLs:

<!-- ❌ Bad -->
<img src="http://localhost:3000/logo.png" />

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

Assets not copied

Ensure build process copies static assets:

vite.config.js

export default defineConfig({
  publicDir: 'public',  // Assets to copy
})

Serverless Function Errors

Problem

API routes or SSR functions return errors.

Common Issues

Missing handler export

Ensure your function exports correctly:

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

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

Missing dependencies

Include dependencies in deployment:

• Check package.json includes all deps
• Verify node_modules in .stormkit/api or .stormkit/server

Timeout

Functions have execution time limits. Optimize slow operations:

• Add database query optimization
• Implement caching
• Use async operations efficiently

Cold start

First request may be slow. Minimize cold starts:

• Keep dependencies lean
• Lazy load heavy modules
• Use connection pooling for databases

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
• Ask in #support channel
• Share deployment logs and error messages

Contact Support

For urgent issues:

• Email: [e-mail]
• Include:
  • App ID
  • Deployment ID
  • Error messages
  • Steps to reproduce

Related Documentation

Configuration

Configure build and deployment settings

How We Deploy

Understand deployment process

System Variables

Environment variables reference

Application Runtime

Server application configuration