Troubleshooting Guide

This document outlines common issues you might encounter and their solutions.

Content Security Policy (CSP)

Resource Loading Errors

If you encounter this error:

Refused to load the image 'https://example.com/thing.png' because it violates the following Content Security Policy directive: "img-src 'self'".

This indicates a CSP restriction. To resolve:

Update CSP Configuration:

// server/index.ts
{
  contentSecurityPolicy: {
    directives: {
      'connect-src': [
        MODE === 'development' ? 'ws:' : null,
        process.env.SENTRY_DSN ? '*.sentry.io' : null,
        "'self'",
      ].filter(Boolean),
      'font-src': ["'self'"],
      'frame-src': ["'self'"],
      'img-src': ["'self'", 'data:', 'https://*.example.com']
    }
  }
}

Best Practices

Start with restrictive policies
Add sources as needed
Document policy changes
Monitor violations

SVG Icon System

Missing Icons Error

If you see:

X [ERROR] Could not resolve "#app/components/ui/icon.tsx"

Solution:

npm run build:icons

Icon Management

// Correct icon import
import { Icon } from '#app/components/ui/icon'
// Usage
<Icon name="user" size={24} />

React Hydration

Hydration Mismatch

When encountering:

Warning: Hydration failed because the initial UI does not match server-rendered HTML.

Common causes and solutions:

Dynamic Content:

// Problematic
function Component() {
  return <div>{new Date().toLocaleString()}</div>
}
// Fixed
function Component() {
const [date, setDate] = useState(() =>
new Date().toLocaleString()
)
return <div>{date}</div>
}

Browser Extensions:

Extensions modifying <head>
Content injection
DOM modifications
Style overrides

Nonce Handling:

// Secure nonce implementation
function getNonce(request: Request) {
  const nonce = createNonce()
  return {
    nonce,
    header: `nonce-${nonce}`
  }
}

Database Issues

Connection Errors

Check Connection String:

// Verify DATABASE_URL format
postgresql://user:password@localhost:5432/dbname

Migration Issues:

# Reset database
npm run db:reset
,[object Object],
npm run db:migrate

Performance Issues

Slow Page Loads

Check Server Timing:

import { time } from '#app/utils/timing.server'
const result = await time(
() => expensiveOperation(),
{ type: 'expensive-op' }
)

Enable Caching:

const data = await cache.fetch(
  'key',
  async () => expensiveOperation(),
  { ttl: 3600 }
)

Environment Setup

Configuration Issues

Verify Environment Variables:

# Check .env file
cat .env
,[object Object],
fly secrets list

Development Setup:

# Reset development environment
npm run clean
npm install
npm run setup

Build Problems

Failed Builds

Clean Build:

# Remove build artifacts
npm run clean
,[object Object],
,[object Object],
,[object Object],
npm run build

Type Errors:

# Run type check
npm run typecheck
,[object Object],
npm run generate

Runtime Errors

Memory Issues

// Monitor memory usage
import { monitorMemoryUsage } from '#app/utils/monitoring'
monitorMemoryUsage({
threshold: 0.8,
interval: 1000
})

Error Handling

// Global error boundary
function ErrorBoundary({ error }: { error: Error }) {
  console.error(error)
  return (
    <div role="alert">
      <h1>Error</h1>
      <pre>{error.message}</pre>
    </div>
  )
}

For more information about security configuration, see the security documentation. For deployment details, refer to the deployment documentation.

Documentation

Getting Started

Core Architecture

Performance & Security

Frontend Resources

Operations

Other Resources

Settings