Troubleshooting

For Everyone

This guide provides solutions to common issues you may encounter when working with Olytix Core. Issues are organized by category for easy navigation.

Installation Issues

Python version incompatibility

Error:

ERROR: Package 'olytix-core' requires a different Python: 3.9.0 not in '>=3.11'

Solution: Olytix Core requires Python 3.11 or later. Check your Python version:

python --version

If needed, install Python 3.11+ using your package manager or pyenv:

# Using pyenv
pyenv install 3.11.0
pyenv local 3.11.0

Dependency installation fails

Error:

ERROR: Could not build wheels for package

Solution:

1. Ensure you have build tools installed:

# Ubuntu/Debian
sudo apt-get install build-essential

# macOS
xcode-select --install

2. Upgrade pip:

pip install --upgrade pip

3. Try installing with verbose output to identify the specific package:

pip install olytix-core -v

Permission denied during installation

Error:

ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied

Solution: Use a virtual environment:

python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

pip install olytix-core

Do not use sudo pip install.

Connection Issues

Cannot connect to database

Error:

ConnectionError: Unable to connect to postgresql://localhost:5432/analytics

Solution:

1. Verify the database is running:

# PostgreSQL
pg_isready -h localhost -p 5432

2. Check your connection settings in olytix-core_project.yml:

warehouse:
  type: postgresql
  host: localhost  # or your actual host
  port: 5432
  database: analytics
  user: ${OLYTIX_DB_USER}
  password: ${OLYTIX_DB_PASSWORD}

3. Verify environment variables are set:

echo $OLYTIX_DB_USER
echo $OLYTIX_DB_PASSWORD

4. Test the connection manually:

psql -h localhost -p 5432 -U $OLYTIX_DB_USER -d analytics

Authentication failed

Error:

AuthenticationError: password authentication failed for user "analytics"

Solution:

1. Verify credentials are correct
2. Check that the user has appropriate permissions:

GRANT ALL PRIVILEGES ON DATABASE analytics TO your_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO your_user;

3. For Snowflake/BigQuery, verify your authentication method (password, key-pair, OAuth)

SSL connection required

Error:

SSLError: SSL connection is required

Solution: Add SSL configuration to your connection:

warehouse:
  type: postgresql
  host: your-host.com
  port: 5432
  database: analytics
  user: ${OLYTIX_DB_USER}
  password: ${OLYTIX_DB_PASSWORD}
  ssl: true
  # or for more control:
  ssl_mode: require

Compilation Issues

Model not found

Error:

CompilationError: Model 'stg_orders' not found

Solution:

1. Verify the model file exists with the correct name:

ls models/**/stg_orders.sql

2. Check for typos in ref() calls:

-- Correct
SELECT * FROM {{ ref('stg_orders') }}

-- Common mistakes
SELECT * FROM {{ ref('stg_order') }}      -- Missing 's'
SELECT * FROM {{ ref('staging_orders') }} -- Wrong name

3. Ensure the model is in the correct directory (under models/)

4. Run compile with verbose output:

olytix-core compile --verbose

Source not found

Error:

CompilationError: Source 'raw.orders' not found

Solution:

1. Verify the source is defined in a YAML file under sources/:

# sources/raw.yml
sources:
  - name: raw
    database: analytics
    schema: public
    tables:
      - name: orders

2. Check the source() call uses the correct source and table names:

SELECT * FROM {{ source('raw', 'orders') }}

Circular dependency detected

Error:

CompilationError: Circular dependency detected: model_a -> model_b -> model_a

Solution:

1. Review your model dependencies and break the cycle
2. Consider using ephemeral materializations for intermediate steps
3. Restructure models to avoid the circular reference

-- Instead of model_a referencing model_b which references model_a,
-- extract shared logic into a third model

-- models/shared_logic.sql
SELECT ...

-- models/model_a.sql
SELECT * FROM {{ ref('shared_logic') }} ...

-- models/model_b.sql
SELECT * FROM {{ ref('shared_logic') }} ...

Invalid YAML syntax

Error:

YAMLParseError: mapping values are not allowed here

Solution:

1. Check for proper indentation (use spaces, not tabs)
2. Verify colons are followed by a space
3. Quote strings with special characters
4. Use a YAML validator or IDE extension

# Incorrect
measures:
- name:my_measure  # Missing space after colon

# Correct
measures:
  - name: my_measure

Query Issues

Measure not found in cube

Error:

QueryError: Measure 'revenue' not found in cube 'orders'

Solution:

1. Verify the measure is defined in the cube:

cubes:
  - name: orders
    measures:
      - name: total_revenue  # Note: name is 'total_revenue', not 'revenue'
        type: sum
        sql: amount

2. Use the correct measure name in your query:

{
  "metrics": ["orders.total_revenue"]
}

Dimension type mismatch

Error:

QueryError: Cannot apply operator 'greater_than' to dimension of type 'string'

Solution: Use appropriate operators for the dimension type:

// For string dimensions
{
  "dimension": "status",
  "operator": "equals",
  "value": "active"
}

// For numeric dimensions
{
  "dimension": "amount",
  "operator": "greater_than",
  "value": 100
}

// For time dimensions
{
  "dimension": "order_date",
  "operator": "after",
  "value": "2024-01-01"
}

Join path not found

Error:

QueryError: No join path found between 'orders' and 'products'

Solution:

1. Define a join between the cubes:

cubes:
  - name: orders
    joins:
      - name: products
        relationship: many_to_one
        sql: "{orders}.product_id = {products}.product_id"

2. Ensure the referenced cube exists and is spelled correctly

Query timeout

Error:

QueryError: Query execution exceeded timeout of 30 seconds

Solution:

1. Add pre-aggregations for the query pattern:

pre_aggregations:
  - name: monthly_revenue
    measures: [total_revenue]
    dimensions: [country]
    time_dimension: order_date
    granularity: month

2. Increase the timeout in configuration:

query:
  timeout: 120  # seconds

3. Optimize the underlying SQL:
   • Add indexes to filtered columns
   • Materialize models as tables instead of views
   • Filter data earlier in the pipeline

API Server Issues

Server fails to start

Error:

ERROR: Application startup failed

Solution:

1. Check if the port is already in use:

lsof -i :8000

2. Use a different port:

olytix-core serve --port 8001

3. Verify the project compiles successfully:

olytix-core compile

API returns 500 Internal Server Error

Solution:

1. Check server logs for details:

olytix-core serve --log-level debug

2. Common causes:
   • Database connection issues
   • Invalid query syntax
   • Missing required configuration

Changes not reflected in API responses

Solution:

1. Recompile the project:

olytix-core compile

2. Restart the API server:

# Stop current server (Ctrl+C)
olytix-core serve

3. Clear any cached pre-aggregations if applicable

Pre-Aggregation Issues

Pre-aggregation not being used

Symptom: Queries are slower than expected despite having pre-aggregations defined.

Solution:

1. Verify the pre-aggregation matches your query pattern:

# Query requests: total_revenue by country and month
# Pre-aggregation must include these exact measures and dimensions
pre_aggregations:
  - name: revenue_by_country_month
    measures: [total_revenue]
    dimensions: [country]
    time_dimension: order_date
    granularity: month

2. Check that the pre-aggregation has been built:

curl http://localhost:8000/api/v1/preaggregations/status

3. Force a pre-aggregation rebuild:

curl -X POST http://localhost:8000/api/v1/preaggregations/refresh

Pre-aggregation build fails

Error:

PreAggregationError: Failed to build pre-aggregation 'monthly_revenue'

Solution:

1. Check for sufficient disk space
2. Verify database permissions for creating tables
3. Review the pre-aggregation SQL for errors:

olytix-core compile --verbose

Lineage Issues

Lineage not showing expected columns

Solution:

1. Ensure models use explicit column references, not SELECT *:

-- Less optimal for lineage tracking
SELECT * FROM {{ ref('stg_orders') }}

-- Better for lineage tracking
SELECT
    order_id,
    customer_id,
    amount
FROM {{ ref('stg_orders') }}

2. Recompile after changes:

olytix-core compile

Incomplete upstream lineage

Solution:

1. Verify all sources are properly defined
2. Check that source column names match actual database columns
3. Ensure models reference sources using source() function

Performance Issues

Slow compilation

Solution:

1. Use parallel compilation:

olytix-core compile --threads 4

2. Reduce the number of models by combining simple transformations
3. Use ephemeral materializations for intermediate steps

High memory usage

Solution:

1. Limit concurrent queries:

server:
  max_concurrent_queries: 10

2. Use streaming for large result sets
3. Add appropriate limits to queries:

{
  "metrics": ["total_revenue"],
  "limit": 1000
}

Getting More Help

Enable debug logging

olytix-core compile --verbose
olytix-core serve --log-level debug

Check the manifest

Review target/manifest.json to understand the compiled state of your project.

Common diagnostic commands

# Check Olytix Core version
olytix-core --version

# Validate project structure
olytix-core validate

# List all artifacts
olytix-core ls

# Test database connection
olytix-core debug connection

---

If your issue is not covered here, check the FAQ or consult the Glossary for term definitions.