Troubleshooting

Common issues and solutions for Wraft development

Troubleshooting Guide

This guide covers common issues encountered during Wraft development and their solutions.

🚀 Installation Issues

Elixir/Erlang Version Mismatch

Problem: Getting version compatibility errors with Elixir or Erlang.

# Check current versions
asdf current
 
# Install correct versions from .tool-versions
asdf install
 
# Verify installation
elixir --version

Always use the versions specified in .tool-versions for consistency.

PostgreSQL Connection Issues

Problem: Cannot connect to PostgreSQL database.

Solutions:

Check PostgreSQL Status

# macOS
brew services list | grep postgresql
brew services start postgresql
 
# Linux
sudo systemctl status postgresql
sudo systemctl start postgresql
 
# Test connection
psql -h localhost -U postgres -c "SELECT version();"

Verify Database Configuration

# Check .env.dev file
cat .env.dev | grep DATABASE
 
# Common settings
DATABASE_URL=postgres://postgres:password@localhost:5432/wraft_dev

Create Database

# Create database and run migrations
mix ecto.create
mix ecto.migrate

MinIO Storage Issues

Problem: MinIO service not starting or connection errors.

Solutions:

# Start MinIO server
minio server ~/minio --console-address :9001
 
# Check if MinIO is running
curl -I http://localhost:9000/minio/health/live
 
# Verify credentials in .env.dev
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_ENDPOINT=http://localhost:9000

🔧 Development Environment

Mix Dependencies Issues

Problem: Dependency compilation failures or conflicts.

Solutions:

# Clean and reinstall dependencies
mix deps.clean --all
mix deps.get
mix deps.compile
 
# For persistent issues
rm -rf _build deps
mix deps.get
mix compile

Phoenix Server Won't Start

Problem: Phoenix server fails to start or crashes.

Common Causes & Solutions:

Port Already in Use

Another process is using port 4000

# Find process using port 4000
lsof -i :4000
 
# Kill the process
kill -9 <PID>
 
# Or use different port
PORT=4001 mix phx.server

Database Migration Issues

Pending migrations or migration errors

# Check migration status
mix ecto.migrations
 
# Run pending migrations
mix ecto.migrate
 
# Reset database if needed
mix ecto.reset

Environment Variables

Missing or incorrect environment variables

# Source environment variables
source .env.dev
 
# Check if variables are loaded
echo $DATABASE_URL
echo $SECRET_KEY_BASE
 
# Generate new secret if needed
mix phx.gen.secret

Compilation Errors

Problem: Elixir compilation errors or warnings.

Solutions:

# Clean compile
mix clean
mix compile
 
# Force recompilation
mix compile --force
 
# Check for syntax errors
mix format --check-formatted

📄 Document Processing Issues

Pandoc Installation

Problem: Pandoc not found or version issues.

# Install via Homebrew
brew install pandoc
 
# Verify installation
pandoc --version
 
# If issues persist, try direct download
# https://github.com/jgm/pandoc/releases

LaTeX Issues

Problem: PDF generation fails due to LaTeX errors.

Solutions:

Install Complete LaTeX Distribution

# macOS
# Download and install MacTeX from https://www.tug.org/mactex/
 
# Linux
sudo apt-get install texlive-full
 
# Windows
# Download and install MiKTeX from https://miktex.org/

Test LaTeX Installation

# Test basic LaTeX
echo '\documentclass{article}\begin{document}Hello World\end{document}' > test.tex
pdflatex test.tex
 
# Check if PDF was generated
ls test.pdf

ImageMagick Issues

Problem: Image processing fails or ImageMagick not found.

Solutions:

# macOS
brew install imagemagick
 
# Linux
sudo apt install imagemagick
 
# Test installation
convert --version
identify --version

Security Policy Issues: ImageMagick may have restrictive security policies. Edit /etc/ImageMagick-6/policy.xml if needed.

🔌 API Issues

Authentication Errors

Problem: API requests return 401 Unauthorized.

Solutions:

Verify API Token

# Check token format
echo $WRAFT_API_TOKEN
 
# Test token with curl
curl -H "Authorization: Bearer $WRAFT_API_TOKEN" \
     http://localhost:4000/api/v1/workspaces

Token Generation

# Generate new token via iex
iex -S mix
> Wraft.Accounts.generate_api_token(user)

CORS Issues

Problem: Cross-origin requests blocked in browser.

Solution:

# In config/dev.exs
config :wraft_web, WraftWeb.Endpoint,
  http: [port: 4000],
  debug_errors: true,
  code_reloader: true,
  check_origin: false  # Allow all origins in development

Rate Limiting

Problem: API requests being rate limited.

Solutions:

# Check rate limit headers
curl -I -H "Authorization: Bearer $TOKEN" \
     http://localhost:4000/api/v1/workspaces
 
# Look for headers:
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 999
# X-RateLimit-Reset: 1640995200

🧪 Testing Issues

Test Database Setup

Problem: Tests fail due to database issues.

Solutions:

# Set test environment
export MIX_ENV=test
 
# Create and migrate test database
mix ecto.create
mix ecto.migrate
 
# Run tests
mix test
 
# Reset test database if needed
mix ecto.reset

Factory Issues

Problem: ExMachina factory errors in tests.

Solutions:

# Ensure factories are properly defined
defmodule Wraft.Factory do
  use ExMachina.Ecto, repo: Wraft.Repo
 
  def user_factory do
    %Wraft.Accounts.User{
      email: sequence(:email, &"user#{&1}@example.com"),
      name: "Test User"
    }
  end
end

Async Test Issues

Problem: Tests fail intermittently due to async issues.

Solutions:

# Use Ecto.Adapters.SQL.Sandbox
setup tags do
  pid = Ecto.Adapters.SQL.Sandbox.start_owner!(Wraft.Repo, shared: not tags[:async])
  on_exit(fn -> Ecto.Adapters.SQL.Sandbox.stop_owner(pid) end)
  %{}
end

🐳 Docker Issues

Container Build Failures

Problem: Docker build fails or takes too long.

Solutions:

# Clear Docker cache
docker system prune -a
 
# Build with no cache
docker-compose build --no-cache
 
# Check for common issues
docker-compose logs wraft

Volume Mount Issues

Problem: File changes not reflected in container.

Solutions:

# In docker-compose.yml
volumes:
  - .:/app
  - /app/deps  # Exclude deps folder
  - /app/_build  # Exclude build folder

Database Connection in Docker

Problem: Container cannot connect to database.

Solutions:

# Use service names in docker-compose
environment:
  - DATABASE_URL=postgres://postgres:password@db:5432/wraft_dev
 
# Ensure database container is ready
depends_on:
  - db

🔍 Debugging Tips

Enable Debug Logging

# In config/dev.exs
config :logger, level: :debug
 
# Or set in environment
export LOG_LEVEL=debug

Use IEx for Debugging

# Start with debugging
iex -S mix phx.server
 
# Add breakpoints in code
require IEx; IEx.pry()
 
# Inspect variables
inspect(variable, pretty: true)

Performance Profiling

# Profile function execution
:timer.tc(fn -> your_function() end)
 
# Use ExProf for detailed profiling
ExProf.profile(fn -> your_function() end)

📚 Getting More Help

Still having issues? Here are additional resources to help you.

💬 Discord Community

Join our developer community for real-time help

🐛 GitHub Issues

Report bugs or search existing issues

📖 Documentation

Review the complete documentation

🔧 Stack Overflow

Search or ask questions with #wraft tag

📋 Diagnostic Commands

Run these commands to gather system information for bug reports:

# System information
uname -a
elixir --version
node --version
 
# Wraft specific
mix --version
mix deps.tree
mix ecto.migrations
 
# Environment
env | grep -E "(DATABASE|S3|WRAFT)"
 
# Log recent errors
tail -n 50 log/dev.log

Pro Tip: Include this diagnostic information when reporting issues to help maintainers debug problems faster.

Previous

Building Wraft

Next

API Reference

On this page