Computed Join Troubleshooting
This page lists common errors you can hit when creating, editing, or running a Computed Join. Each section names the user-visible message, the underlying cause, and the resolution. Use your browser search to find the exact text of the message you saw.
Duplicate container name
Cause: A container with this name already exists on the parent datastore, including containers that were deleted and not yet purged.
Resolution: Pick a unique name, or rename the conflicting container.
403 Forbidden on Create, Edit, or Delete
The exact wording varies by action and ownership:
You don't have permission to create this computed asset. You must either have [Editor] permission on the datastore, or have [Author] permission and be the owner of the asset
Only the computed container owner (Author) or an Editor can modify this container
Only the computed container owner (Author) or an Editor can delete this container
Only the computed container owner (Author) or an Editor can modify these settings
Authors cannot change computed asset ownership; only an Editor can reassign the owner
Cause: Your team permission on the left datastore is below what the action requires. Editors can act on any Computed Join; Authors can act only on the Computed Joins they own, and cannot transfer ownership even when they are the current owner.
Resolution: Ask a datastore Editor (or an Admin) to perform the action, transfer ownership to you, or grant you the Editor team permission. See Computed Join Permissions for the full matrix.
Computed Join used as input
Cause: The chosen left or right container is another Computed Join. Computed Joins cannot be used as inputs to another Computed Join.
Resolution: Materialize the input join's result as a Computed Table, then use that Computed Table as the input. See Supported Inputs.
Input container not profiled
Cause: The chosen container has never been profiled. A Computed Join requires both inputs to be profiled first.
Resolution: Profile the input container, then retry creating the join.
Mismatched join field types
Cause: The chosen join fields on the left and right have incompatible data types (for example, string vs decimal).
Resolution: Where possible, cast one side using a Computed Field on the input container so the joined fields share a type. If a Computed Field isn't a fit for the input type, pick a different pair of fields whose types already match, or transform the data upstream.
DISTINCT in the Select Expression
Spark SQL select clause can not use the distinct() function, consider using the field expression `explode(collect_set(your_field_name)) as distinct_field_values` for your use case
Cause: The Select Expression includes any form of DISTINCT: the bare keyword, DISTINCT(col), aggregate forms like COUNT(DISTINCT col), SUM(DISTINCT col), APPROX_COUNT_DISTINCT(col), or multi-column variants.
Resolution: Replace DISTINCT col with explode(collect_set(col)). Add a GROUP BY only if your Select Expression also includes columns that are not aggregated. See Best Practices.
Semicolon in the Select or Filter clause
Multi-statement SQL detected in SELECT clause. Only expressions are allowed. Clause prefix: <prefix>
Cause: The clause contains a semicolon, suggesting multiple SQL statements. Only a single expression or predicate is allowed. The WHERE clause variant ends with Only boolean expressions are allowed, and the LATERAL VIEW variant ends with Only generator expressions are allowed.
Resolution: Remove the semicolon.
Validation timeout
Cause: Validating the join definition against the input containers took longer than the configured timeout.
Resolution: Retry. If it keeps timing out, simplify the query or narrow each side by materializing a filtered Computed Table or Computed File and using it as the input. If the timeout persists, contact your administrator. (API callers can raise the timeout_seconds query parameter on POST /containers/validate up to 300 seconds, see the API reference.)
Join field no longer exists
Cause: The configured join field no longer exists in the input container (renamed or removed upstream).
Resolution: Edit the Computed Join, pick a current field from the affected side, and save.
Select Expression references a missing column
Valid column names could not be parsed from the select clause [<your clause>]. Did you forget to escape special characters?
Cause: The Select Expression references a column that no longer exists in the joined output. This usually happens when an upstream input container had a field renamed or dropped, and the Computed Join's Select Expression still points to the old prefixed name. The platform validates the Select Expression on every save and on each scan or profile.
Resolution: Open the failing Computed Join and update the Select Expression to use the current prefixed field names from the left and right inputs (left prefix + underscore + original field name, same for the right side). Save again to retrigger validation. If the field was intentionally renamed upstream, rebuild the Select Expression around the new name.
Input container marked as Unloadable
Container '<name>' is marked as Unloadable. No attempt was made to load it due to multiple consecutive failures in prior operations
Cause: The input container failed three consecutive scan or profile operations and was marked Unloadable. Qualytics short-circuits any join that uses it until the status clears.
Resolution: Open the input container and follow the recovery steps for its type: run a Sync for tables, views, and file patterns, or Edit + Validate + Save for Computed Tables and Computed Files used as inputs. See Scan Troubleshooting for the full procedure.
Where Clause references a missing column
Cause: The Where Clause references a column that no longer exists in the joined output. This is the Where Clause counterpart to the Select Expression failure above. Because the Where Clause path does not have a dedicated friendly message, the user sees the raw SQL analyzer error.
Resolution: Open the failing Computed Join and update the Where Clause to use the current prefixed field names. The error often includes a suggestion with the closest matching column name. Save again to retrigger validation.
Input container too large for one load pass
Cause: The container has more data than the deployment can load in one pass during the join.
Resolution: Narrow each side by materializing a filtered Computed Table or Computed File and using it as the input. Reduce the columns in the Select Expression. If neither is enough, request additional capacity from your administrator.
GROUP BY validation failure (missing column)
Cause: The Select Expression includes columns that are neither aggregated nor present in the Group By Clause.
Resolution: Either add the column to the Group By Clause, or wrap it in an aggregation function (SUM, MAX, COUNT, etc.).
GROUP BY validation failure (column not found)
Column not found when applying groupByClause for <name>. Check that all columns in selectClause and groupByClause exist after the join.
Cause: A column referenced in the Group By Clause does not exist in the joined result. This usually happens when prefixes don't match the column alias.
Resolution: Inspect the prefixed column names produced by the join (left prefix + underscore + original field name, same for the right side) and update the Group By Clause to reference the exact prefixed names.
GROUP BY without aggregations
Invalid groupByClause for <name>: selectClause must include aggregations (SUM, AVG, MAX, MIN, etc.) for non-group-by columns
Cause: A Group By Clause was provided, but the Select Expression contains no aggregation functions.
Resolution: Either add at least one aggregation function (SUM, MAX, COUNT, etc.) to the Select Expression, or remove the Group By Clause.
Duplicate column names (prefix collision)
Cause: Two columns in the joined output resolve to the same name after prefixing. The most common trigger is identical Left Prefix and Right Prefix (defaults are left and right; if both are changed to the same value, every shared column name collides). Other triggers: a hand-aliased column in the Select Expression collides with a prefixed one, or the same alias is reused. The configuration is accepted at save time and only fails when validation runs.
Resolution: Open the join configuration and set distinct values for Left Prefix and Right Prefix. If the prefixes are already distinct, find the colliding pair in the Select Expression and either add an explicit AS <alias> to one of them, or remove the duplicate. Save again to retrigger validation.
Connection timed out to the datastore
Cause: One side of the join could not establish a connection to the source datastore after three retry attempts with exponential backoff.
Resolution: Confirm the datastore is reachable from your Qualytics deployment (network, security group, credentials, datastore availability). If the datastore is healthy, retry. If retries keep failing, contact your administrator.
Container referenced by quality checks (delete)
Cause: Quality checks elsewhere reference this Computed Join (for example, an Aggregation Comparison, Exists In, Not Exists In, or Data Diff check using the joined output).
Resolution: Delete or re-target the referencing quality checks, then retry the delete.
Container is input to a Computed Join (delete)
Container id: <id> is being used by the following computed join containers: <ids> that must be deleted first
Cause: You are trying to delete a base container or computed asset that one or more Computed Joins reference as input.
Resolution: Delete the Computed Joins first, then the input container.
Removed fields warning on Save
This change will mark the following fields as missing, preserving their quality checks and anomalies. Set force_drop_fields=true to proceed.
Cause: The edited Select Expression removes fields that have active quality checks or anomalies. The server returns the message above; the UI surfaces a shorter "Fields will be marked as missing" banner with the same intent.
Resolution: Click Review Expression to adjust the Select Expression to keep those fields, or click Proceed Anyway to apply the edit. The dropped fields are marked missing, and their quality checks and anomalies are preserved until they reappear in a future edit.