# AQL Troubleshooting

> Trace AQL errors to their source, diagnose unexpected results (ambiguous joins, unconnected models, LOD), and use the AMQL sandbox to isolate and test fixes.

This is one of three documents aimed at helping answer common questions about AQL:
1. [Troubleshooting](/as-code/reference/troubleshooting) (this guide)
2. [AQL Error Reference](/reference/aql/error-reference)

This guide covers two main topics:
- How to [identify the source of an error](#narrow-down-error-source) when you're stuck
- How to [resolve common issues](#error-resources) and get unstuck

## Identify the Source of an Error {#narrow-down-error-source}

When faced with an AQL error, your first step should be to identify the exact source of the problem. Most errors can be traced to a specific field (metric or dimension) in your code.

The problematic code will typically be highlighted in red, within the definition of the field causing the error, as shown in this example:

This visual indication should provide enough information to help you fix most errors. If you need additional context or the error message isn't clear, consult the resources listed below.

## Helpful Resources {#error-resources}

### Documentation Resources

## Troubleshooting Errors

If your visualization returns an error, consult:

- [AQL Error Reference](/reference/aql/error-reference):
  A comprehensive guide to AQL error codes with explanations and solutions. Error messages in AQL include direct links to relevant sections of this guide.

## Unexpected Results
If your visualization runs without errors but produces unexpected results, consider these common causes:

- [Ambiguous relationships](/as-code/reference/common-relationships-problems#ambiguous-relationships):
  Your dataset may have multiple possible relationship interpretations. The system's chosen interpretation might differ from your intended logic.
- [Unconnected models](/as-code/reference/common-relationships-problems#unconnected-models):
  If metrics remain unchanged when adding dimensions or filters, or if values repeat across rows, your dimension/filter models may not be properly connected to the metric's model. This prevents them from affecting the results.
- [Level of Details](/as-code/aql/cookbook/level-of-detail):
  Using LOD functions can alter how metrics respond to dimensions and filters. Review your LOD expressions to ensure they align with your analysis goals.

### Testing and Reproduction

#### AMQL Online Sandbox

If the documentation doesn't resolve your issue, the [AMQL online sandbox](https://play.amql.org) can be invaluable for troubleshooting:

- Create a minimal reproduction of your problem
- Isolate specific AQL code segments to identify issues
- Test potential fixes in a controlled environment

Using the sandbox allows you to simplify complex queries and focus on the specific components causing errors, making it easier to find solutions.