Troubleshooting & FAQ

Common Issues

Installation Issues

Bun not found

# Error: bun: command not found

Solution: Install Bun globally:

curl -fsSL https://bun.sh/install | bash
# Then restart your terminal or run:
source /.bashrc  # or /.zshrc

Permission denied during installation

# Error: EACCES: permission denied

Solution: Don't use sudo with Bun. Fix npm permissions:

mkdir -p ~/.bun
chown -R $(whoami) ~/.bun

Stacks CLI not found after installation

# Error: buddy: command not found

Solution: Ensure Bun's bin directory is in your PATH:

export PATH="$HOME/.bun/bin:$PATH"
# Add to _{/.bashrc or}/.zshrc for persistence

Development Server Issues

Port already in use

# Error: Port 3000 is already in use

Solution: Either kill the process or use a different port:

# Find and kill process
lsof -i :3000
kill -9 <PID>

# Or use different port
buddy dev --port 3001

Hot reload not working

Possible causes and solutions:

File watcher limit reached (Linux):

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

File saved outside project: Ensure you're editing files within the project directory.
Ignored files: Check if the file is in .gitignore or bunfig.toml ignore patterns.

HTTPS certificate errors in development

# Error: NET::ERR_CERT_AUTHORITY_INVALID

Solution: Trust the development certificate:

buddy dev:cert --trust
# Or manually add to system trust store

Database Issues

Connection refused

# Error: ECONNREFUSED 127.0.0.1:5432

Solutions:

Ensure database is running:

# With Pantry
pantry service start postgres

# Or check status
pantry service status postgres

Verify connection settings in .env:

DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=myapp
DB_USERNAME=postgres
DB_PASSWORD=password

Migration failed

# Error: relation "users" already exists

Solution: Reset migrations (development only):

buddy migrate:fresh  # Drops all tables and re-runs migrations
# Or rollback and retry
buddy migrate:rollback
buddy migrate

SQLite database locked

# Error: SQLITE_BUSY: database is locked

Solution: Enable WAL mode in config:

// config/database.ts
sqlite: {
  journal: 'wal',
  busyTimeout: 5000,
}

Build Issues

TypeScript errors

# Error: Type 'X' is not assignable to type 'Y'

Solutions:

Run type check for details:

buddy typecheck

Clear TypeScript cache:

rm -rf node_modules/.cache
bun run build

Regenerate types:

buddy types:generate

Out of memory during build

# Error: JavaScript heap out of memory

Solution: Increase Node.js memory limit:

NODE_OPTIONS="--max-old-space-size=4096" buddy build

Module not found

# Error: Cannot find module '@/components/Button'

Solutions:

Check path aliases in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./app/*"]
    }
  }
}

Reinstall dependencies:

rm -rf node_modules bun.lockb
bun install

Authentication Issues

Session not persisting

Solutions:

Check session driver:

# .env
SESSION_DRIVER=redis  # Ensure Redis is running

Verify cookie settings:

// config/auth.ts
session: {
  secure: process.env.NODE_ENV === 'production', // false for http://localhost
  sameSite: 'lax',
}

CSRF token mismatch

# Error: CSRF token mismatch

Solutions:

Include CSRF token in forms:

<form method="POST">
  <x-csrf />
  <!-- form fields -->
</form>

Include header in AJAX requests:

fetch('/api/endpoint', {
  method: 'POST',
  headers: {
    'X-XSRF-TOKEN': getCookie('XSRF-TOKEN'),
  },
})

Deployment Issues

Cloud deployment fails

Common causes:

Missing environment variables:

buddy cloud:check  # Validates deployment config

Build errors:

buddy build --production  # Test production build locally

Insufficient permissions:

# Verify AWS credentials
aws sts get-caller-identity

Application crashes in production

Debugging steps:

Check logs:

buddy logs:tail --env=production

Verify environment:

buddy cloud:ssh
cat .env  # Check production environment

Health check:

curl https://your-app.com/health

Frequently Asked Questions

General

Q: What version of Bun is required?

A: The audited Stacks source declares Bun ^1.3.0, Git 2.47.0, and SQLite ^3.47.2. Use the project-pinned toolchain rather than upgrading Bun independently. With Pantry-managed projects:

pantry install
buddy doctor

Q: Can I use npm or yarn instead of Bun?

A: No, Stacks is built specifically for Bun and uses Bun-specific features. While some packages may work with Node.js, the framework requires Bun.

Q: Is Stacks production-ready?

A: Stacks.js is pre-1.0 and capability-specific. Web/API, database, auth, queue, real-time, provider, cloud, and desktop paths do not share one maturity level. Pin the exact source/package versions, consult the generated evidence and maturity matrices, and test the selected drivers and topology under your workload. A schema-valid protocol report exists, but its profile claim is null.

Q: How do I update Stacks?

A: Review the installed command help and upgrade guide before changing a 0.x version:

buddy upgrade --help
buddy doctor
buddy test
buddy test:types

Architecture

Q: Can I use React or Vue components?

A: Stacks uses STX, a Blade-inspired templating engine. While you cannot directly use React/Vue components, STX provides similar component capabilities with a simpler mental model.

Q: Does Stacks support GraphQL?

A: GraphQL support is planned for a future release. Currently, Stacks focuses on REST APIs with full type safety.

Q: Can I use Stacks for just the backend?

A: Yes. Stacks can run an API without application STX views. Create a normal project with the current recommended command, then configure only the services your API needs:

panx @stacksjs/buddy new my-api
cd my-api
buddy dev api

Q: How do I add a custom database driver?

A: Implement the DatabaseDriver interface and register it:

// drivers/CustomDriver.ts
export class CustomDriver implements DatabaseDriver {
  // Implementation
}

// config/database.ts
import { CustomDriver } from './drivers/CustomDriver'
connections: {
  custom: {
    driver: CustomDriver,
    // config
  }
}

Performance

Q: How does Stacks compare to Express/Fastify?

A: There is no framework-wide multiplier that applies across workloads. Compare pinned production builds with equivalent routing, validation, serialization, database work, payloads, hardware, concurrency, and error accounting. Publish the load script and raw results; see the performance methodology page.

Q: How do I enable caching?

// Using cache helper
const users = await cache.remember('users:all', 3600, async () => {
  return await User.all()
})

Q: Why is my development server slow?

A: Common causes:

Large node_modules (use Bun's faster resolution)
Too many file watchers (increase limit)
Sync operations blocking event loop (use async)

Database

Q: Which databases are supported?

A: PostgreSQL, MySQL, SQLite, and DynamoDB. MongoDB support is planned.

Q: How do I run raw SQL queries?

const results = await DB.raw('SELECT * FROM users WHERE age > ?', [18])

Q: Can I use multiple databases?

A: Yes, define multiple connections and specify which to use:

const user = await User.on('replica').find(1)

Deployment

Q: Where can I deploy Stacks apps?

Serverless: AWS Lambda (via ts-cloud)
Containers: Any Docker host, Kubernetes
VMs: Any Linux server with Bun installed
Edge: Cloudflare Workers (planned)

Q: How do I set up CI/CD?

A: Example GitHub Actions workflow:

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      - run: bun install
      - run: bun run test
      - run: bun run build
      - run: buddy deploy --env=production

Q: How do I handle secrets in production?

A: Use environment variables, never commit secrets:

# Set via ts-cloud
buddy cloud:secret set DATABASE_PASSWORD "your-password"

# Or use AWS Secrets Manager/Parameter Store

Debugging

Q: How do I debug Stacks applications?

VS Code: Use the Bun debugger extension
CLI: Use buddy tinker for REPL
Logging: Use Clarity for structured logs

Q: How do I inspect database queries?

// Enable query logging
// config/database.ts
export default {
  logging: {
    queries: true,
    slowQueryThreshold: 100, // ms
  }
}

Q: How do I profile performance?

# Built-in profiler
buddy profile --duration=60

# Or use Bun's built-in profiler
bun --inspect run start

Error Reference

Common Error Codes

Code	Message	Solution
`E_VALIDATION`	Validation failed	Check request data against validation rules
`E_AUTH`	Authentication required	Ensure user is logged in
`E_FORBIDDEN`	Access denied	Check user permissions
`E_NOT_FOUND`	Resource not found	Verify resource exists
`E_RATE_LIMIT`	Too many requests	Wait and retry, or increase limits
`E_DATABASE`	Database error	Check connection and query
`E_CONFIG`	Configuration error	Verify config files

Stack Trace Reading

When you see an error like:

Error: Cannot find user
    at UserController.show (/app/Controllers/UserController.ts:25:11)
    at Router.handle (/node_modules/@stacksjs/router/src/index.ts:142:20)
    at processRequest (/node_modules/@stacksjs/server/src/index.ts:89:15)

First line: The error message
Second line: Where the error originated in YOUR code
Following lines: Framework internals (usually less relevant)

Focus on the first file path in your application code (not in node_modules).

Getting Help

If you can't find a solution:

Search existing issues: GitHub Issues
Ask on Discord: Real-time community help
Create an issue: Include reproduction steps, error messages, and environment info