Troubleshooting

This document contains solutions to common issues encountered when working with the PermaplanT backend.

Build Issues

Schema Generation Errors

Problem: Build fails with diesel CompatibleType errors like:

error[E0277]: the trait bound `((Float, ...), ...): CompatibleType<..., ...>` is not satisfied

Root Cause: This error typically occurs when the generated schema.rs file is out of sync with the actual database schema, often due to:

  • Incomplete or failed database migrations
  • Manual database schema changes not reflected in migrations
  • Time synchronization issues causing incorrect file modification times

Solution: Regenerate the database schema by running:

make reset-database

This command will:

  1. Drop and recreate the database
  2. Run all migrations to ensure schema consistency
  3. Insert sample/scraped data
  4. Generate a fresh schema.rs file that matches the database

Alternative Solution (if you want to preserve existing data):

make migrations

PostgreSQL Client Library Connection Issues

Problem: Build fails with PostgreSQL client library connection errors on macOS, typically when using Postgres.app.

Root Cause: The Rust build process cannot locate the PostgreSQL client libraries installed by Postgres.app.

Solution: Set the RUSTFLAGS environment variable to point to the PostgreSQL library directory:

export RUSTFLAGS="-L /Applications/Postgres.app/Contents/Versions/latest/lib"

Alternative Solutions:

  • If using a different PostgreSQL installation, adjust the path accordingly:

    # For Homebrew PostgreSQL
export RUSTFLAGS="-L $(brew --prefix postgresql)/lib"

# For system PostgreSQL
export RUSTFLAGS="-L /usr/local/lib"

  • Make the setting permanent by adding it to your shell profile (.bashrc, .zshrc, etc.)

Database Issues

Migration Failures

Problem: make migrations fails with permission or extension errors.

Solution: Ensure your database user has the necessary permissions:

sudo -u postgres psql
ALTER USER permaplant WITH SUPERUSER;

PostGIS Extension Missing

Problem: Database operations fail due to missing PostGIS extension.

Solution: The extension should be installed automatically during migrations. If it fails, install manually:

sudo -u postgres psql -d permaplant_db
CREATE EXTENSION IF NOT EXISTS postgis;