🎉 The Architech v1.0 is now available. Read more →
Troubleshooting

Troubleshooting

Common issues and solutions when using The Architech.

Installation Issues

"command not found: architech"

Problem: CLI not in PATH after installation.

Solution:

# If you used npm link
npm link
 
# Or add to PATH manually
export PATH="$PATH:./node_modules/.bin"
 
# Verify installation
which architech
architech --version

"Cannot find module @thearchitech.xyz/marketplace"

Problem: Marketplace not linked or installed.

Solution:

# In marketplace directory
cd marketplace
npm link
 
# In CLI directory
cd ../Architech
npm link @thearchitech.xyz/marketplace
 
# Rebuild
npm run build

Genome Resolution Issues

"Genome not found: saas-starter"

Problem: Genome name not recognized or marketplace not found.

Solutions:

  1. Check available genomes:
architech list-genomes
  1. Use file path instead:
architech new ../marketplace/genomes/official/03-full-saas-platform.genome.ts
  1. Verify marketplace location:
# The CLI looks for marketplace in:
# 1. ../marketplace (relative to CLI)
# 2. node_modules/@architech/marketplace
# 3. Custom sources in architech.config.json
  1. Check for typos in genome name: The CLI will suggest similar genomes if name is close.

"Genome file not found: /path/to/genome.ts"

Problem: File path is incorrect.

Solution:

# Use absolute path
architech new /Users/you/path/to/genome.ts
 
# Or relative from current directory
architech new ./genomes/my-genome.ts
 
# Verify file exists
ls -la path/to/genome.ts

Generation Errors

"Failed to execute TypeScript genome"

Problem: Genome file has syntax errors.

Solutions:

  1. Check genome syntax:
// Must use defineGenome()
import { defineGenome } from '@thearchitech.xyz/marketplace/types';
 
export default defineGenome({  // ← Must be default export
  project: { ... },
  modules: [ ... ]
});
  1. Verify TypeScript compilation:
npx tsc --noEmit genome.ts
  1. Check for missing imports: Make sure defineGenome is imported correctly.

"Invalid genome structure: missing project"

Problem: Genome missing required fields.

Solution: Ensure genome has all required fields:

export default defineGenome({
  version: '1.0.0',      // Required
  project: {              // Required
    name: 'my-app',       // Required
    framework: 'nextjs',  // Required
  },
  modules: []             // Required (can be empty)
});

"Module X not found in marketplace"

Problem: Referenced module doesn't exist.

Solutions:

  1. Check module ID spelling:
# Correct
{ id: 'framework/nextjs' }
 
# Wrong
{ id: 'frameworks/nextjs' }  # ← plural
{ id: 'nextjs' }              # ← missing category
  1. Verify module exists:
ls -la marketplace/adapters/framework/nextjs/
  1. Check marketplace is built:
cd marketplace
npm run build

Database Issues

"DATABASE_URL environment variable not set"

Problem: Missing database connection string.

Solution:

# Copy .env.example
cp .env.example .env
 
# Add your database URL
echo 'DATABASE_URL="postgresql://user:pass@host:5432/db"' >> .env
 
# Or use Neon (free tier)
# 1. Sign up at neon.tech
# 2. Create database
# 3. Copy connection string to .env

"relation does not exist" error

Problem: Database schema not created.

Solution:

# Push schema to database
npm run db:push
 
# Or run migrations
npm run db:migrate

Authentication Issues

"GITHUB_CLIENT_ID not set"

Problem: Missing OAuth credentials.

Solution:

# 1. Create GitHub OAuth App:
#    https://github.com/settings/developers
 
# 2. Set callback URL:
#    http://localhost:3000/api/auth/callback/github
 
# 3. Add to .env:
echo 'GITHUB_CLIENT_ID="your_client_id"' >> .env
echo 'GITHUB_CLIENT_SECRET="your_secret"' >> .env

"AUTH_SECRET is required"

Problem: Missing auth secret key.

Solution:

# Generate random secret
openssl rand -base64 32
 
# Add to .env
echo 'AUTH_SECRET="<generated-secret>"' >> .env

Payment Issues

"Stripe key not configured"

Problem: Missing Stripe API keys.

Solution:

# 1. Sign up at stripe.com
# 2. Get test API keys from dashboard
# 3. Add to .env:
 
echo 'STRIPE_SECRET_KEY="sk_test_..."' >> .env
echo 'STRIPE_WEBHOOK_SECRET="whsec_..."' >> .env
echo 'NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."' >> .env

"Webhook signature verification failed"

Problem: Webhook secret doesn't match.

Solution:

# 1. In Stripe dashboard, add webhook endpoint:
#    http://localhost:3000/api/webhooks/stripe
 
# 2. Copy webhook signing secret
# 3. Update .env with correct secret

Build/Runtime Errors

"Module not found" errors after generation

Problem: Dependencies not installed.

Solution:

# Install dependencies
npm install
 
# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

TypeScript errors in generated code

Problem: Type mismatches (rare, but possible).

Solution:

# Regenerate types
npm run db:generate  # For Drizzle
npm run type-check   # Check all types
 
# Update dependencies
npm update

Performance Issues

Generation is slow

Expected behavior:

  • Simple genomes: 30-60 seconds
  • Intermediate: 2-5 minutes
  • Advanced: 5-15 minutes

Slow network?:

# Check npm registry
npm config get registry
 
# Use faster mirror (optional)
npm config set registry https://registry.npmmirror.com

"npm install" taking forever

Solution:

# Use pnpm (faster)
pnpm install
 
# Or yarn
yarn install
 
# Or skip install during generation (then install manually)
# Add to genome:
options: {
  skipInstall: true
}

Development Issues

"Hot reload not working"

Solution:

# Restart dev server
npm run dev
 
# Clear Next.js cache
rm -rf .next
npm run dev
 
# Check port isn't in use
lsof -i :3000

"Tailwind classes not applying"

Solution:

# Verify tailwind.config.ts content paths
# Should include: "./src/**/*.{js,ts,jsx,tsx,mdx}"
 
# Restart dev server
npm run dev

Getting Help

Still stuck?

  1. Check logs:
# The CLI outputs detailed logs
architech new my-app --genome saas-starter --verbose
  1. Search documentation:
  1. Community help:
  1. Debug mode:
# Dry run to see what would happen
architech new my-app --genome saas-starter --dry-run
 
# Verbose logging
architech new my-app --genome saas-starter --verbose

Common Error Messages Decoded

"Missing prerequisite capability"

Meaning: A module requires another module to be installed first.

Solution: The error message will suggest which adapter to add. Add it to your genome.

"Template file not found"

Meaning: A blueprint references a missing template file.

Solution: This is usually a marketplace issue. Report it on GitHub.

"VFS flush failed"

Meaning: Could not write generated files to disk.

Solution:

  • Check disk space
  • Check file permissions
  • Verify output directory exists and is writable

"Blueprint execution failed"

Meaning: A module's blueprint encountered an error.

Solution:

  1. Run with --verbose to see details
  2. Check if prerequisites are met
  3. Verify module parameters are correct
  4. Report to GitHub if it seems like a bug

Reporting Bugs

If you've found a bug:

  1. Verify it's reproducible:
# Try with --dry-run first
architech new test-app --genome hello-world --dry-run
 
# Then try actual generation
architech new test-app --genome hello-world --verbose
  1. Gather information:
  • CLI version: architech --version
  • Node version: node --version
  • Operating system
  • Full error message
  • Genome file content (if custom)
  1. Report on GitHub: Create an issue (opens in a new tab) with the information above.

Not finding your issue? Ask in Discord (opens in a new tab) or open a discussion (opens in a new tab).

CookbookOverview