Skip to content

Troubleshooting Guide

Common issues and solutions for Constellation development.

Development Server Issues

Server Won't Start

Problem: bun dev fails or port already in use

Solutions: 

# Check if port is in use
lsof -i :3000

# Kill process
kill -9 <PID>

# Clear Next.js cache
rm -rf .next

# Restart
bun dev

Server Crashes on Start

Problem: Error: ENOENT: no such file or directory

Solutions: 

# Install dependencies
bun install

# Create missing config files
touch .env.local

# Ensure backend services are running
curl http://localhost:8001/health

Hot Module Replacement (HMR) Not Working

Problem: Changes don't reflect without manual refresh

Solutions: 

# Restart dev server
bun dev

# Check for errors in console
# Check .next folder is writable
chmod -R u+w .next

# Rebuild
rm -rf .next
bun dev

TypeScript Issues

Type Errors After Changes

Problem: 'type' only refers to a type but is being used as a value

Solutions: 

// ❌ WRONG
import { User } from '@/src/types/user';

// ✅ CORRECT - Use 'type' keyword for type imports
import type { User } from '@/src/types/user';

Cannot Find Module

Problem: Cannot find module '@/src/...'

Solutions: 1. Check path is correct 2. Verify file exists 3. Check tsconfig.json paths 4. Restart TypeScript server in IDE

Strict Mode Errors

Problem: TypeScript reports errors that weren't there before

Solutions: 

// Add explicit types
const value: string = 'test';

// Use non-null assertion (carefully)
const element = document.getElementById('id')!;

// Use optional chaining
const name = user?.profile?.name;

Testing Issues

Tests Fail Locally but Pass in CI

Problem: Inconsistent test behavior

Solutions: 

# Clear test cache
rm -rf .vitest
bun test:run

# Run with verbose output
bun test -- --reporter=verbose

# Check for flaky tests
bun test -- --repeat=3

MSW Mock Not Working

Problem: API calls not being intercepted

Solutions: 

// Ensure server is set up
import { server } from '@/src/test/mocks/server';

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());

// Check handler matches request
http.get('/api/users/:id', ({ params }) => {
  console.log('Handler called with:', params);
});

Component Tests Fail

Problem: Element not found or Cannot update unmounted component

Solutions: 

// Wait for elements
await waitFor(() => {
  expect(screen.getByText('Content')).toBeInTheDocument();
});

// Use act() for state updates
act(() => {
  result.current.updateState();
});

// Don't test implementation details
// ❌ Test if setState was called
// ✅ Test if UI updated

Build Issues

Build Fails

Problem: bun build exits with error

Solutions: 

# Check for TypeScript errors
bun run build

# Clear cache
rm -rf .next

# Check for missing dependencies
bun install

# Fix linting errors
bun lint --fix

Bundle Size Too Large

Problem: Build produces large bundle

Solutions: 

# Analyze bundle
npm run build:analyze

# Code split with dynamic imports
import dynamic from 'next/dynamic';
const Component = dynamic(() => import('./Component'));

# Tree shake unused code
# Check imports aren't importing entire modules

Performance Issues

Page Loads Slowly

Problem: Slow time to first paint

Solutions: 1. Check Network tab in DevTools 2. Identify slow API requests 3. Implement request caching 4. Use Image component for images 5. Implement lazy loading

Component Re-renders Excessively

Problem: Component renders too often

Solutions: 

// Memoize components
export const Component = memo(function MyComponent(props) {
  // ...
});

// Memoize callbacks
const handleClick = useCallback(() => {
  // ...
}, [dependencies]);

// Memoize expensive computations
const value = useMemo(() => {
  return expensiveOperation(data);
}, [data]);

Authentication Issues

Can't Login

Problem: Login fails or redirects to login loop

Solutions: 1. Check OAuth credentials in .env.local 2. Verify redirect URL matches OAuth config 3. Check browser console for errors 4. Clear browser cookies/localStorage

Token Expired

Problem: Session expires and user is logged out

Solutions: 

// Implement automatic token refresh
apiClient.addResponseInterceptor(
  (response) => response,
  (error) => {
    if (error.status === 401) {
      return tokenService.refreshToken()
        .then(() => retry(error.config));
    }
    throw error;
  }
);

CORS Error

Problem: Cross-Origin Request Blocked

Solutions: 1. Check backend has CORS enabled 2. Verify NEXT_PUBLIC_API_URL is correct 3. Use API route as proxy:

// src/app/api/proxy/[...path]/route.ts
export async function GET(request: Request) {
  const path = request.url.split('/api/proxy/')[1];
  const response = await fetch(
    `${process.env.NEXT_PUBLIC_API_URL}/${path}`,
    {
      headers: request.headers,
    }
  );
  return response;
}

i18n Issues

Translations Not Updating

Problem: Language doesn't change or translations missing

Solutions: 

# Check translation files exist
ls public/locales/en/
ls public/locales/fr/

# Check i18n configuration
cat src/i18n/i18n.ts

# Reload page after language change
window.location.reload();

Missing Translation Keys

Problem: Placeholder text shows instead of translation

Solutions: 1. Check key name matches JSON file 2. Verify JSON syntax is correct 3. Reload application 4. Add missing key to translation file

Database Connection Issues

Can't Connect to API

Problem: API requests fail with connection error

Solutions: 

# Check backend is running
curl http://localhost:8001/health

# Check .env.local has correct URL
cat .env.local | grep NEXT_PUBLIC_API_URL

# Check firewall isn't blocking
ping localhost

# Restart backend services
docker-compose restart api

Git Issues

Can't Push to Repository

Problem: Permission denied or auth failed

Solutions: 

# Set git credentials
git config --global user.email "you@example.com"
git config --global user.name "Your Name"

# Use SSH key
ssh-add ~/.ssh/id_rsa
git remote set-url origin git@github.com:org/repo.git

Merge Conflicts

Problem: CONFLICT when pulling or merging

Solutions: 

# See conflicts
git status

# Edit files and remove conflict markers
# Then resolve
git add .
git commit -m "Resolve conflicts"
git push

Environment Variables

Variables Not Loading

Problem: Environment variables are undefined

Solutions: 

# Verify .env.local exists
ls -la .env.local

# Verify variables are set
cat .env.local

# Variables must start with NEXT_PUBLIC_ to be available in browser
NEXT_PUBLIC_API_URL=http://localhost:8001

# Restart dev server
bun dev

Wrong Environment Used

Problem: Using production API in development

Solutions: 

# Check current environment
echo $NODE_ENV

# Verify .env.local (development)
# vs .env.production (production)

# Restart with correct environment
NODE_ENV=development bun dev

Browser Issues

Content Not Showing

Problem: Page appears blank

Solutions: 1. Open DevTools (F12) 2. Check Console for errors 3. Check Network tab for failed requests 4. Check Elements for rendered content 5. Hard refresh (Ctrl+Shift+R)

Styling Not Applied

Problem: Classes don't work or layout broken

Solutions: 

# Rebuild Tailwind
rm -rf .next
bun dev

# Check class name is correct
# Check Tailwind config includes the file
# Check @apply rules are valid

JavaScript Not Running

Problem: Interactive features don't work

Solutions: 1. Check for JavaScript errors in console 2. Verify 'use client' in interactive components 3. Check dependencies are installed 4. Verify hooks are used correctly

IDE/Editor Issues

TypeScript Intellisense Not Working

Problem: No autocomplete in VSCode

Solutions: 

# Restart TypeScript server
# In VSCode: Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server"

# Check tsconfig.json is valid
bun run build

# Reinstall dependencies
bun install

ESLint Not Fixing Issues

Problem: bun lint --fix doesn't fix everything

Solutions: 

# Check ESLint config
cat eslint.config.mjs

# Run specific rule
bun lint -- --fix src/

# Disable rule if conflicting
// eslint-disable-next-line rule-name

Recovery Steps

Full Reset

When everything is broken:

# 1. Clear dependencies
rm -rf node_modules bun.lockb

# 2. Clear caches
rm -rf .next .vitest build

# 3. Reinstall
bun install

# 4. Run build
bun run build

# 5. Start dev
bun dev

Check Everything

# 1. Dependencies
bun install

# 2. Build
bun run build

# 3. Linting
bun lint

# 4. Types
npx tsc --noEmit

# 5. Tests
bun test:run

# 6. Dev server
bun dev

Getting Help

  1. Search docs: Check FAQ.md first
  2. Google search: Include error message + "Constellation"
  3. Check GitHub Issues: Already reported?
  4. Ask team: Slack or team discussion
  5. Create issue: With reproduction steps

Reporting Issues

When creating a bug report:

  1. Title: Clear, specific description
  2. Steps to Reproduce: Exact steps to trigger
  3. Expected vs Actual: What should happen vs what happens
  4. Environment: OS, Node version, browsers
  5. Logs: Console errors, stack traces
  6. Attachments: Screenshots, video if helpful

Last Updated: January 2026
Can't find your issue here? Create a new issue