> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lume.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common errors and solutions when using the Lume Python SDK.

This guide covers common issues you might encounter while using the Python SDK and how to resolve them. For detailed information on the specific exceptions the SDK can raise, see the [Exceptions API Reference](/pages/libraries/python-ent/api/classes/exceptions).

## Local Environment

### SDK can't find the API Key

* **Cause**: The `LUME_API_KEY` environment variable is not set or is not accessible to the Python script's process.
* **Solution**:
  1. Verify the environment variable is set in the *same terminal session* where you are running your script.
  2. Use `print(os.getenv("LUME_API_KEY"))` in your Python script to see what value is being read. It will print `None` if the variable is not found.
  3. Remember that IDEs or cron jobs may not inherit the environment variables from your shell profile (`.bashrc`, `.zshrc`). Ensure the variable is set in the correct context for your execution environment.

## Authentication Errors

If the SDK cannot authenticate with the Lume platform, it will raise an `AuthenticationError`.

* **Cause**: This is typically due to a missing, incorrect, or revoked API key.
* **Solution**:
  1. Verify that your `LUME_API_KEY` environment variable is set correctly.
  2. If using `lume.init()`, ensure the `api_key` argument is correct.
  3. Generate a new API key in the Lume UI under **Settings > API Keys** and update your configuration.

## Invalid Request Errors

If you successfully authenticate but the request itself is invalid, the SDK will raise an `InvalidRequestError`.

* **Cause**: This usually means the `flow_version` does not exist or your `source_path` is malformed. It can also be triggered by Lume's idempotency check.
* **Solution**:
  1. Check for typos in the flow name and version string (e.g., `"my-flow:v1"`).
  2. Ensure the Flow Version you are targeting has been **published** in the Lume UI. You cannot execute a draft.
  3. Verify your API key has "Execute" permissions for the Flow.
  4. **Check for Idempotency**: If you are intentionally trying to re-process a `source_path` that has already completed successfully, the API will raise an `InvalidRequestError` to prevent duplicate runs. To override this, use the `force_rerun=True` parameter in your `lume.run()` call.

## Run-Time Failures

These errors occur *during* a pipeline's execution on the Lume platform.

### Run fails with status `FAILED`

A `FAILED` status indicates a non-recoverable error occurred in one of the pipeline stages. When using `run.wait()`, this will raise a `RunFailedError`.

#### Error Code: `SourceConnectorError`

This is one of the most common errors and occurs during the `SYNCING_SOURCE` stage.

* **Solution**:
  1. **Check Credentials**: In the Lume UI, navigate to the Connector used by your Flow Version and verify its credentials (e.g., IAM role ARN, database password) are correct.
  2. **Check Permissions**: Ensure the Connector's credentials have `read` permissions for the specific `source_path` you are trying to access.
  3. **Check Network Access**: If your data source is in a VPC, ensure Lume's dedicated IP addresses are on your firewall's allowlist.
  4. **Check Path Syntax**: Double-check that the `source_path` is correctly formatted. For S3, it should be `s3://bucket/key`. For databases, it's a string identifier for the data to be processed.

#### Error Code: `TargetConnectorError`

This is similar to `SourceConnectorError` but occurs during the `SYNCING_TARGET` phase.

* **Solution**:
  1. **Check Credentials**: Verify the credentials for the Target Connector.
  2. **Check Permissions**: Ensure the Connector's credentials have `write` permissions to the target location (e.g., `s3:PutObject` for S3, `INSERT` for databases).

### Run status is `PARTIAL_FAILED`

This is not a true failure. It means the pipeline completed, but some rows failed transformation.

* **Solution**:
  1. Inspect the `run.metadata['results']` object, specifically the `rejected_rows` count and the `target_locations['rejects']` path.
  2. See the [Handling Partial Failures](/pages/libraries/python-ent/advanced#handling-partial-failures) guide for advanced strategies.

## Common Workflow Issues

### Accessing Results Before Run Completion

* **Symptom**: `AttributeError` or unexpected `None` values when trying to access `run.metadata`.
* **Cause**: The `run.metadata` attribute is only populated *after* the run has reached a terminal state (`SUCCEEDED`, `FAILED`, etc.). If you access it immediately after calling `lume.run()`, it will be empty.
* **Solution**: Always call `run.wait()` or `run.refresh()` before accessing `run.metadata` to ensure the object has been updated with the final results from the Lume platform.

### Unexpected Data Handling

* **Symptom**: A run succeeds but produces 0 rows, or seems to process the wrong data.
* **Cause**: This can happen if the `source_path` points to an empty file or a database query that returns no results.
* **Solution**:
  1. Verify the source data at the specified `source_path` is not empty.
  2. Check the `input_rows` field in `run.metadata['results']` to confirm how many rows Lume ingested from your source.
  3. If using a database connector, double-check the query logic within the Lume UI to ensure it's selecting the intended data.

## Performance Issues

### `run.wait()` takes a very long time or times out

If `run.wait()` exceeds its timeout, it will raise a `RunTimeoutError`. This can happen for several reasons:

* **Large Data Volume**: Syncing or transforming a very large amount of data can take a long time.

* **Complex Transformations**: A highly complex Flow Version can increase processing time.

* **Source/Target Bottlenecks**: Performance issues in your own data stores can slow down the sync stages.

* **Troubleshooting Steps**:
  1. **Check Run Status**: Before it times out, you can check the run's `status` to see which stage is taking the longest (`SYNCING_SOURCE`, `TRANSFORMING`, or `SYNCING_TARGET`). You can do this by calling `run.refresh()` in a separate thread, or by checking the run status in the Lume UI.
  2. **Review Run Metrics**: After a run completes, inspect `run.metadata['pipeline']` for a detailed timing breakdown of each stage.
  3. **Increase Timeout**: If the long runtime is expected, increase the `timeout` parameter in your `run.wait(timeout=...)` call.

### `ApiError` or other connection errors

If the SDK raises a generic `ApiError` during a `run.wait()` poll or a `lume.run()` call, it typically indicates a transient network issue between your application and the Lume API.

* **Solution**:
  * Implement a retry mechanism with exponential backoff around your API calls to make your application more resilient. The example in the [Advanced Topics](/pages/libraries/python-ent/advanced#advanced-run-monitoring) guide shows how to do this for run monitoring.

## Tips for Effective Debugging

When encountering an issue that you cannot resolve, gathering the right information is key to a quick resolution. Before reaching out for support, please have the following details ready:

* **Run ID**: The unique identifier for the run (`run_...`). This is the most important piece of information.
* **Flow Version**: The exact flow and version string used (e.g., `invoice_processor:v4`).
* **Source Path**: The `source_path` that triggered the run.
* **Error Message**: The full traceback from the Python SDK, if any.
* **Time of Occurrence**: The approximate time (including timezone) when the error occurred.
* **Code Snippet**: A small, self-contained snippet of your Python code that reproduces the issue.