Troubleshooting¶
No reports available¶
Check that your business app is in INSTALLED_APPS and that its qbe.py uses
@register. The logged-in user must be active staff with model view permissions.
For a related field, also grant the target model’s view permission. An empty
catalog is intentional until these requirements are met.
The report is empty although Admin shows rows¶
The report combines the visible conditions with get_queryset(request).
Django Admin may use a different row policy. Remove conditions temporarily to
distinguish the query from the report’s access scope. A superuser still follows
that scope; they do not automatically receive every row. See Reports and permissions
for an explicit superuser policy. Empty results do not disclose how many rows
exist outside the user’s scope.
Preview returns a generic error¶
Look for Report request failed (<ExceptionClass>). in your application’s
server logs. A FieldError can mean that get_queryset(request) refers to
a nonexistent field. The installation example uses owner because its models
have that field; adapt it to your model, such as user or a tenant relationship.
Keep SQL, credentials and real query data out of public bug reports.
System checks fail¶
Run python manage.py check and correct the registration:
Check ID |
Configuration problem |
|---|---|
|
Missing/invalid nonempty fields tuple |
|
Duplicate, malformed or unknown field paths |
|
Unsupported field, relationship, multiple hop or composite key |
|
Target report or terminal field is not registered |
|
Labels do not map declared paths to text |
A duplicate report or missing policy method can raise ImproperlyConfigured
at startup before system checks run.
Login or static assets do not work¶
Keep the default Django admin route, session/authentication/messages middleware
and CSRF middleware. The standard admin template configuration must be present.
Use collectstatic and your normal static serving setup outside development.
A custom AdminSite is not automatically adopted by this version.
A filter is rejected¶
Use an operator offered for the field. Decimal values must be finite text, UUIDs
and dates must parse, and Boolean JSON values must be actual booleans. Use
isnull for nulls and distinguish false, zero and empty text from missing input.
Review Build and export queries for format validators and text fragment lookups.
Report or CSV is incomplete¶
Check the report cap and truncation notice/header. A PostgreSQL timeout may abort an expensive query. Add appropriate indexes in the host application and choose budgets for your workload. CSV interrupted after its headers may end without an HTML error page. Logs identify the exception class; inspect your own database monitoring for the underlying failure without exposing sensitive query input.
A summary has two distinct bounds. QBE2_MAX_AGGREGATE_ROWS limits authorized
source rows and rejects the request before returning any partial total.
QBE2_MAX_ROWS limits completed groups shown or exported and reports truncation.
Raise the source bound only after considering memory and request time.
SQLite Decimal summaries¶
SQLite stores DecimalField values using numeric affinity, which can involve
binary floating-point. Django QBE 2 uses scaled integer sums for Decimal metrics
when the model field precision and configured source cap fit SQLite’s integer
range. A larger field is rejected with an actionable error so a rounded total is
not presented as exact. Use PostgreSQL for those high-precision Decimal summaries.
Unsupported behavior¶
Generic relations, more than two relationship hops, multiple collection edges in one field, multi-database selection and visual diagrams are unsupported. Describe the intended workflow and constraints in a GitHub issue instead of working around server-side restrictions with arbitrary SQL.