> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.instabase.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.instabase.com/_mcp/server.

# Error handling

> Handle and troubleshoot errors in results.

Understanding how automation apps handle empty or null results can help you troubleshoot extraction issues and handle errors in downstream systems.

When a result can't be extracted for a specific field, the field returns either an empty string (`""`) or `null`. These values are displayed differently across AI Hub interfaces.

| Interface                                                        | Condition                                 | Display message            | Actual value   |
| ---------------------------------------------------------------- | ----------------------------------------- | -------------------------- | -------------- |
| Project editor                                                   | Result is `""` or `null` with no cleaning | No value found             | `""` or `null` |
| Project editor                                                   | Result is `""` or `null` after cleaning   | Cleaning returned no value | `""` or `null` |
| Project editor                                                   | Custom function error                     | Custom function error      | Error details  |
| Ground truth datasets and accuracy tests                         | Result is `""` or `null`                  | No value found             | `""` or `null` |
| Human review                                                     | Result is `""`                            | No value found             | `""`           |
| Human review                                                     | Result is `null`                          | null                       | `null`         |
| Exported results, downstream integrations, and API/SDK responses | Result is `""` or `null`                  | raw value                  | `""` or `null` |

## Handling empty results in custom functions

When writing custom functions, treat both `""` and `null` as empty values to ensure predictable behavior across different extraction scenarios.

When processing app results through APIs or integration functions, implement error handling for empty field values.

```python
def process_field_value(field_result):
    """Handle different empty value scenarios."""

    # Check for null or empty string
    if field_result is None or field_result == "":
        # Apply business logic for missing values
        return "NOT_FOUND"

    return field_result
```

## Customizing error messages

Customize how automation apps handle missing values using specific prompts or custom functions.

* **Field prompts** -- Include instructions like *If not found, return 'Not Available'* in your field description or prompt.

* **Cleaning function** -- Transform empty results into standardized messages.

  ```python

  def standardize_empty(previous_line, context):
      """Standardize empty field responses."""
      if not previous_line or previous_line.strip() == "":
          return "Not Found"
      return previous_line
  ```

* **Validation function** -- Flag empty values for human review when the field is required.

  ```python

  def validate_required_field(field_value, context):
      """Ensure required fields have values."""
      if not field_value or field_value.strip() == "":
          return "This field is required"
      return None
  ```

## Troubleshooting extraction failures

If fields consistently return empty values, try these troubleshooting steps.

* **Review field configuration** -- Verify that the field name and description accurately describe the data you want to extract, and that the field type is appropriate to the data.

* **Check digitization quality** -- Poor OCR quality can prevent successful extraction. Review digitization settings and view the document in text-only view to verify that the data you want to extract is present and legible.

* **Test with different models** -- Some models perform better with specific document types or extraction scenarios.