Troubleshooting¶

Home > Guides > Troubleshooting

Common issues and solutions when working with the Ingenious Fabric Accelerator.

Environment Setup Issues¶

Command not found: ingen_fab¶

Problem: After installation, the command ingen_fab is not recognized.

Solutions: 1. Activate your virtual environment:

source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

1. Install in development mode:

   pip install -e .[dev]
   

2. Check PATH (for global installs):

   echo $PATH
   pip show insight-ingenious-for-fabric
   

Environment variable errors¶

Problem: Commands fail with "FABRIC_WORKSPACE_REPO_DIR must be set" or similar.

Solution: Set up environment variables to avoid specifying them on each command:

# Project location
export FABRIC_WORKSPACE_REPO_DIR="./sample_project"

# Target environment
export FABRIC_ENVIRONMENT="development"

# Authentication (for deployment)
export AZURE_TENANT_ID="your-tenant-id"
export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"

# Project location
$env:FABRIC_WORKSPACE_REPO_DIR = "dp"

# Target environment
$env:FABRIC_ENVIRONMENT = "development"

# Authentication (for deployment)
$env:AZURE_TENANT_ID = "your-tenant-id"
$env:AZURE_CLIENT_ID = "your-client-id"
$env:AZURE_CLIENT_SECRET = "your-client-secret"

See Environment Variables for a complete list.

CLI Command Issues¶

DDL compilation fails¶

Problem: ingen_fab ddl compile fails with template errors.

Solutions: 1. Check your DDL script syntax:

python ddl_scripts/Lakehouses/Config/001_Initial_Creation/001_create_tables.py

1. Verify variable library exists:

   ls fabric_workspace_items/config/var_lib.VariableLibrary/valueSets/
   

2. Check for missing Jinja template variables.

Deployment failures¶

Problem: ingen_fab deploy deploy fails with authentication errors.

Solutions: 1. Use Azure CLI authentication:

az login
az account show  # Verify login

1. Or set service principal variables:

   export AZURE_TENANT_ID="your-tenant-id"
   export AZURE_CLIENT_ID="your-client-id" 
   export AZURE_CLIENT_SECRET="your-client-secret"
   

2. Verify workspace access in the Fabric portal.

Testing Issues¶

Local tests fail¶

Problem: ingen_fab test local python fails.

Solutions: 1. Set environment to local:

export FABRIC_ENVIRONMENT=local

1. Install dev dependencies:

   uv sync  # or pip install -e .[dev]
   

2. Check for missing test dependencies like PostgreSQL/SQL Server for local testing.

Import errors in notebooks¶

Problem: Generated notebooks can't import python_libs.

Solutions: 1. Upload Python libraries to Fabric:

ingen_fab deploy upload-python-libs

1. Check library compilation:

   ingen_fab libs compile
   

Configuration Issues¶

Variable resolution fails¶

Problem: Variables like {{fabric_environment}} don't resolve in notebooks.

Solutions: 1. Verify your value set file exists:

cat fabric_workspace_items/config/var_lib.VariableLibrary/valueSets/development.json

1. Check variable names match exactly (case-sensitive).

2. Recompile notebooks after variable changes:

   ingen_fab ddl compile --output-mode fabric_workspace_repo --generation-mode Warehouse
   

Workspace not found¶

Problem: Deployment fails with "workspace not found" errors.

Solutions: 1. Check workspace ID is correct (from Fabric portal URL). 2. Verify you have access to the workspace. 3. Try using workspace name instead:

ingen_fab init workspace --workspace-name "My Workspace"

Package Issues¶

Package compilation fails¶

Problem: ingen_fab package ingest compile fails.

Solutions: 1. Check target datastore is valid:

ingen_fab package ingest compile --target-datastore lakehouse  # or warehouse

1. Include samples for first-time setup:

   ingen_fab package ingest compile --include-samples
   

Performance Issues¶

Slow DDL compilation¶

Problem: DDL compilation takes very long.

Solutions: 1. Check for large Jinja templates. 2. Reduce number of DDL scripts being compiled. 3. Use specific generation mode rather than both:

ingen_fab ddl compile --generation-mode Warehouse  # instead of both

Getting Help¶

1. Use built-in help:

   ingen_fab --help
   ingen_fab COMMAND --help
   

2. Check logs: Look for detailed error messages in console output.

3. Verify prerequisites: Ensure Python 3.12+, required dependencies installed.

4. Test step-by-step: Break complex workflows into individual commands.

Common Error Messages¶

Debug Mode¶

Enable verbose output for more detailed error information:

# Most commands support --verbose
ingen_fab ddl compile --verbose

For persistent issues, create a minimal reproducible example and check the project documentation for specific component troubleshooting.