Experiencing an issue with TQRouting? This guide covers common installation, licensing, configuration and optimisation problems, along with recommended troubleshooting steps.
For detailed technical guidance, refer to the TQRouting Documentation.
TQRouting won't install
If you encounter an installation error, check that:
You're using a supported Python version (3.11–3.14).
Your operating system and architecture are supported.
Your Python environment is correctly configured.
You have access to the required package repository.
Your pip installation is up to date.
To update pip, run:
python -m pip install --upgrade pipFor installation commands and supported platforms, see the Installation Guide.
Python cannot import TQRouting
If you encounter an import error:
Confirm that the package installed successfully.
Check that you're using the correct Python environment.
Verify that the package is installed in that environment.
Restart your Python session and try again.
Where can I find my TQRouting licence?
Visit the Terra Quantum application switcher.
Sign in using your Terra Quantum ID (TQID).
Select Licenses.
For licence requests, activation assistance or renewals, contact Terra Quantum Support.
I'm receiving a licence error
TQRouting requires a valid licence to run.
Check that:
Your licence has been configured correctly.
The TQROUTING_LICENSE_KEY environment variable is set, if you're using this activation method.
You're using the correct licence for TQRouting.
Your environment can establish the network connection required for licence verification.
For configuration instructions, see the Installation Guide.
If the issue persists, contact Support with the error message. Do not share your licence key.
My routing problem fails validation
Validation errors may be caused by:
Missing or incorrectly formatted input data.
Invalid customer or vehicle parameters.
Inconsistent distance or duration matrices.
Incorrectly configured constraints.
Review your input data and refer to the Problem Definition Guide.
TQRouting cannot find a feasible solution
Some routing problems may have constraints that cannot all be satisfied simultaneously.
Check that:
Your fleet has sufficient capacity.
Customer time windows are achievable.
Route duration and distance limits are reasonable.
Pickup and delivery requirements are consistent.
Your distance and duration matrices contain valid values.
If necessary, simplify the problem or relax selected constraints to identify the source of infeasibility.
My optimisation is taking longer than expected
Solver performance depends on problem size, complexity, constraints and available computational resources.
Consider:
Reviewing the complexity of your routing problem.
Checking solver time limits and configuration.
Using appropriate computational resources.
Testing a smaller problem to establish a baseline.
For configuration options, see Solver Configuration.
The results don't match my expectations
If your routing solution differs from your expected outcome:
Review the configured optimisation objectives.
Check the input distances, travel times and constraints.
Confirm that vehicle and customer parameters are correct.
Review the solution metrics and feasibility information.
Refer to Reading Results for guidance.
I'm having trouble with OSRM or Google Maps integration
If you're using an external routing service to generate distance or duration matrices:
Check that the service is accessible.
Confirm any required API credentials or configuration.
Verify that your locations and coordinates are valid.
Review the generated matrix data for missing or unexpected values.
For details, see Distance & Duration Matrices.
If you're unable to resolve an issue, visit the Terra Quantum Help Centre.
Our AI-assisted support widget can help you find relevant documentation and troubleshooting guidance, with access to our Support team when needed.
Alternatively, email [email protected].
When reporting an issue, please include:
Python and TQRouting package versions
Operating system and execution environment
A description of the issue
Relevant error messages or logs
Steps to reproduce the problem, where possible
A minimal reproducible example, if available
Please avoid including licence keys, passwords or sensitive routing data.
Related articles
Overview & Getting Started
User Guide & Key Workflows
Licensing & Access
Reporting a Technical Issue