Troubleshoot Golden

Start from the symptom, use customer-visible product state, and stop before repeating a data-changing action whose outcome is uncertain.

Access is denied

• 401: verify that the credential is present, current, and intended for the Golden environment.
• 403: verify that the authenticated user or token has the role required for the operation.
• 423: inspect whether the entity or resource is disabled or locked before retrying.
• Do not solve a permission issue by distributing an administrator token.

See Golden security.

An entity is not ready

Search returns no records

1. Confirm the entity is READY and supports search.
2. Confirm the request fields belong to the entity’s dataset.
3. Try a known record and a smaller set of criteria.
4. Distinguish a successful empty result from an authorization or validation error.
5. If records were just written, confirm any asynchronous processing has completed.

A task does not complete

Confirm the task identifier, current status, progress time, and displayed messages. A cancellation request is not final until the task reaches CANCELLED. Do not start another run until you know whether the first can still change data.

See Follow tasks and product events.

A destination is not receiving data

1. Confirm the producing task completed.
2. Open Events for the intended destination.
3. Review pending or invalid product events and their displayed messages.
4. Resolve access, validation, or destination availability.
5. Ask an administrator to reactivate the event before retrying delivery.
6. Do not clear events unless the approved recovery procedure intends to discard them.

No duplicates are detected

Golden groups records before it compares them. If obvious duplicates never appear as candidates, work backwards through the phases:

1. Confirm the entity type supports duplicate resolution — NONE and SEARCH entities do not produce candidates.
2. Confirm indexing has run since the records were loaded. Reindex if not.
3. Review the indexer mappings, including whether duplicates is enabled for the relevant mapping.
4. Check column names, normalization, matching type, and compound-key choices. Records that never land in the same group are never compared, whatever the classifier thresholds are.

See How Golden resolves duplicates.

Unrelated records are being merged

Stop automatic stewardship while investigating. The cause may be comparison configuration, an overbroad steward rule, or a manual decision; a high classification alone does not apply a merge.

1. Open an incorrectly matched group and read its match evidence to see which field drove the decision.
2. Check whether that field is genuinely identifying. A shared household address or a shared company phone number is not.
3. Test whether a higher matchThreshold routes the affected cases to REVIEW.
4. Reconsider the classifier mapping, weight, semantic comparison, and text options for the field responsible.
5. If a steward resource is merging automatically, disable it until the thresholds are corrected. See Configure automatic stewardship.

For an already completed merge, first assess merge undo. It requires retained contributors and the other recovery conditions. After restoration, disconnect the records that must remain separate. Disconnect does not itself reconstruct absorbed records.

Known duplicates are classified as different

Inspect the comparison evidence and thresholds for a verified duplicate pair.

1. Confirm the records are in the same candidate group at all. If not, this is an indexing problem, not a classification one.
2. Check whether the relevant indexer and classifier settings are too strict for legitimate variations in that field.
3. Raise the weight on the fields that genuinely identify the subject.
4. Test whether a lower nonMatchThreshold routes the affected cases to REVIEW.
5. Verify known matches and non-matches before applying the revised configuration.

Too many groups are waiting for review

Review volume depends on the data, mappings, thresholds, and group-size rules. Inspect representative cases and improve missing or malformed comparison fields. Test threshold changes against known matches and non-matches before using them to reduce the queue. See Indexer configuration and Classifier configuration for candidate selection and classification thresholds. Data quality provides the separate validation context.

An entity is INCONSISTENT

Configuration and processed state disagree, usually after a configuration change that has not been applied to existing data.

1. Identify whether the dataset, indexer, classifier, merger, source, or sink configuration changed.
2. Run entity synchronization with the appropriate supported masks and wait for the task to complete.
3. If the state persists, check the most recent failed task for a validation message naming the conflict.

A resource cannot be saved or deleted

• Validation fails on save. Re-send the configuration with test set to true to see the validation message on its own. Check that every referenced resource identifier exists and is spelled as stored.
• Deletion is refused. The resource is still referenced by an entity or another resource. Find and update the referring object; the refusal is a safeguard, not a fault. See Manage resources.

A load or ETL task fails

Read the failure detail before retrying. The task keeps a progress message showing how far it reached; inspect errorType and errorMessage on the run.

Fix the cause and inspect any partial effects before retrying. Administrators can request POST /api/jobs/runs/{id}/retry when the run is eligible. A retry is a new execution attempt, not a rollback or a guarantee against duplicate writes. See Tasks and schedules.

Records loaded but do not appear

1. Confirm the load task reached SUCCEEDED, not merely that it was accepted.
2. Read the task messages and quality or validation details for the operation.
3. Query the table directly with table queries. If the records are in the table but not in search, synchronize the relevant index and classification work.
4. If the table contains the record but search does not, inspect the record’s index status.

An account is locked

Repeated failed sign-ins can lock an account. An administrator can use the explicit unlock operation, or the user can follow the supported password recovery flow. If it locks repeatedly, check for a stale stored credential before unlocking it again. See Manage users.

If the problem continues

Collect only customer-safe evidence:

• Golden product version;
• time range and environment name;
• affected entity, table, destination, task, or event identifier;
• operation and terminal status;
• HTTP status and X-Trace-Id; and
• displayed validation or error messages with sensitive record values removed.

Never send an authorization header, API token, password, full customer record, or internal diagnostic material through an unapproved channel.