Troubleshoot Policy

• 1: Troubleshoot Authoring and Review
• 2: Known Issues and Workarounds
• 3: Recover Publication and Withdrawal
• 4: Reconcile a Policy's Native Ownership
• 5: Remove Verified-Stale Ownership Mappings
• 6: Troubleshoot Automatic Recompilation
• 7: Common Policy Errors
• 8: Collect Policy Diagnostics
• 9: Recover Policy Safely
• 10: Troubleshoot Installation, Identity, and Routing

1 - Troubleshoot Authoring and Review

Use this task when saving, submission, review, or approval fails. Application programming interface (API) callers must retain response headers and details. An existing governed revision can remain current while replacement draft work fails. Do not infer a delivery failure from a draft validation error.

Prerequisites

Prepare the following:

• Identify the policy and the exact action that failed.
• Use your own authenticated identity.
• Read roles and permissions.
• Retain the returned error and any support reference.

Check Permissions Before Retrying

Check these separate authorization requirements:

1. Identify the command’s required capability. Submission requires policy:edit. Requesting changes requires policy:review. Approval requires policy:approve.
2. Check applicable policy access grants for authoring. Edit authority alone does not replace an active owner or editor grant.
3. Ask a Protegrity Provisioned Cluster (PPC) user with administrator permissions to correct a missing command permission. For a missing owner/editor grant, ask an existing owner of that policy.

Ownership does not grant review or approval capability. An author role does not create review authority. Use your deployment’s approved authority mapping. Do not request broad administration by default. A reviewer describes a responsibility, not a separate policy_reviewer product role.

Different users can author, review, and approve. Policy does not impose a universal two-person approval requirement. Follow any additional separation-of-duties rules in your organization.

Use the Token for the Resource You Change

An authentication token proves caller identity. A resource validator identifies the version you inspected. Do not interchange them.

Use this table to identify the resource evidence required for each task:

Complete the following steps:

1. Read the current policy with GET /policies/{policy_id}. Keep both response validators distinct.
2. Compare the current draft with the content you intended to change. Resolve another user’s changes before attempting your decision again.
3. Obtain the current saved validation as an authorized reviewer. Use GET /policies/{policy_id}/validation. It requires policy:review.
4. Use the current reviewed draft token for the intended draft command. Do not construct it from a visible version number.
5. Read GET /policies/{policy_id} again. Check that the draft status reflects your command and that the saved content includes your intended changes.

An author without review authority must hand validation inspection to a reviewer. After submission, the reviewer must reload the submitted draft and use its new Draft-ETag value. The author’s pre-submission token is no longer the review token.

A missing token can return 428. Draft commands can return 400 for the wrong token kind or 409 for a changed head. Request-changes reports a mismatched token as 409. Archive can return 412 for stale governed-policy evidence. Read the response. Do not treat every 409 as the same failure.

Resolve Validation and Conflict Findings

Complete the following steps:

1. Read the returned error message and each issue’s path and message. If an issue names a policy field, compare that field with the request you sent.
2. Correct draft fields that you control. Resolve blocking conflicts rather than treating every finding as an acknowledgement choice.
3. Send directory, connection, or discovery errors to the administrator of the named integration. Include the error and support reference. Do not change unrelated policy fields to clear an integration error.
4. Save corrected work through the normal authoring task. Saving does not submit or approve the policy.
5. Ask an authorized reviewer to refresh validation for the saved head. Current dependencies can change findings even when draft text remains unchanged.
6. Submit or review through the lifecycle tasks. Acknowledge only permitted findings with the required notes and current conflict identifiers.

Hard permission-widening conflicts do not become safe through acknowledgement. Missing classification, protector, or identity evidence can require an external owner. Refer to restricted diagnostics when an auditor must inspect configuration details.

Handle Returned Work and Approval

When a reviewer requests changes, the author should retain the reason. Correct and save the draft before resubmitting eligible current work. The reviewer uses their own authenticated account for the next decision. Policy derives actor identity from authentication. Do not send submittedBy, approvedBy, or spoofed identity headers.

Approval queues publication. It does not prove delivery or protection. If approval succeeds but delivery stalls, switch to publication recovery. Do not repeatedly approve merely because protection remains incomplete.

Verification and Stop Conditions

Reload the policy and check the saved content, draft status, and recorded decision actor. After approval, follow the delivery verification guides.

Use the diagnostic handoff if you cannot obtain the required permission, current validator, or integration details. Do not discard another user’s work, override hard conflicts, or share credentials.

Refer to API authentication and API operation reference for exact request contracts.

2 - Known Issues and Workarounds

Use this reference before installation and when a documented limitation matches your symptoms. An issue entry is not a general instruction to replace credentials or relax permissions. Record installed component versions when reporting an occurrence.

Identity Provider Secret Backfill After Traverse

Condition and Reported Behavior

This issue concerns Policy installed after an existing Traverse deployment.

The reported behavior leaves the shared identity provider (IdP) connection Secret unpopulated. Existing Traverse connection details do not automatically backfill it when Policy is installed later. Policy can therefore lack the connection metadata required for member-source provisioning. Workload readiness alone does not establish that this metadata exists.

Workaround

The reported workaround is to save the existing IdP connection details again in Traverse. The connection owner should use their authorized connection-management workflow after Policy installation. Preserve the intended settings and existing credentials. Do not rotate passwords, recreate the connection, or reinstall Policy merely to trigger this update.

If re-saving does not populate the Secret, ask the platform operator to verify the configured scanner identity. The chart’s idpSecret.writer must name the actual scanner ServiceAccount and namespace. Its permission is limited to patching the named Secret in the Policy namespace. Do not grant broad Secret permissions as a workaround.

Verification

Find the configured Secret name in the chart’s idpSecret.name value. The default namespace is pty-policy. Its default data key is sources.json. Set IDP_SECRET_NAME to that Secret name and CTX to the intended Kubernetes context. An authorized operator can check key presence without printing connection values:

kubectl --context "$CTX" --namespace pty-policy get secret \
  "${IDP_SECRET_NAME:?Set IDP_SECRET_NAME to the configured Secret name}" \
  -o go-template='{{if .data}}{{if index .data "sources.json"}}sources.json: present{{else}}sources.json: missing or empty{{end}}{{else}}sources.json: missing or empty{{end}}{{"\n"}}'

Use your configured Secret name, namespace, and key when defaults differ. present confirms only that the key contains bytes. It does not prove valid JavaScript Object Notation (JSON), the expected provider entry, or usable directory credentials.

Have the authorized integration owner verify the expected connection entry through approved tools. Then repeat the operation that previously lacked member-source configuration. Keep Secret values, bind passwords, and tokens out of logs and support attachments. Escalate if the entry remains absent or the original operation still fails.

Refer to shared identity provider metadata and Kubernetes and directory identities. Use the diagnostic handoff for an unresolved occurrence.

3 - Recover Publication and Withdrawal

Use this task when a policy reports a publication or removal error after approval or archive. Policy performs these operations in the background, so the approval or archive request can succeed before delivery finishes. Withdrawal means removing this policy’s previously published configuration from the receiving products.

Prerequisites

Prepare the following:

• Identify the policy and failed publication or withdrawal.
• Obtain policy:audit for operation inspection, or involve an authorized auditor.
• Obtain policy:approve for publication retry or policy:archive for withdrawal retry.
• Follow the diagnostic request setup for application programming interface (API) examples.

In Policy Panel, open the affected policy’s Operations tab for visible evidence. If you cannot open it, send the policy name and visible error to your Policy administrator. The remaining steps require the permissions listed above.

Find the Latest Publication or Removal Request

Each publication or removal request has a generation number. A larger number identifies a later request for the same policy. Retries remain part of the same request and increase its attempt count.

Complete the following steps:

1. Read GET /policies/{policy_id}/operations with policy:audit, or open the policy’s Operations tab.
2. Select the entry with the largest generation number. For example, if the response contains generations 7 and 8, investigate 8 rather than retrying 7.
3. Copy that entry’s deploymentId, operation, lastError, and diagnostics into your incident record. The operation field distinguishes publication from removal. diagnostics can provide a message, remediation, and support reference.
4. Match the error description to the next-action table below. If the message does not explain the failure, send these details to your Policy administrator rather than guessing a repair.

If replacedByGeneration names a later request, investigate that request instead. An earlier failed publication might precede a later removal request. Retrying the earlier work is not the intended recovery.

An operations 404 can mean no recorded deployments. Confirm the policy separately before concluding that it does not exist.

Choose the Authorized Recovery Path

The descriptions below illustrate failure types. They are not exact error-message strings.

Use this table to match a failure description with its next action:

If requiresOperatorAction is true, include the diagnostic message, remediation, and supportReference in your administrator handoff. If retryable is false, investigate the diagnostic rather than forcing a retry.

If Guardrails retrieval succeeds but the policy remains Published, check the consumer identity and current receipt. The empty-string consumer setting accepts absent or empty request identity, not named requests. A nonempty setting requires an exact gateway-verified username match. A missing qualifying receipt is not failed retained publication work. Retrying publication cannot repair an identity mismatch or establish runtime activation.

Retry Retained Work

Complete the following steps:

1. Ask the administrator identified in the table to confirm that the reported problem is resolved.

2. Read the operation list again and confirm that the same request remains the latest and has retryable: true. If a later request exists, investigate it instead.

3. Set DEPLOYMENT_ID to that operation’s exact deploymentId. Use the appropriate publication or withdrawal capability.

4. Send the retry request:

   curl --silent --show-error --include --cacert "$PPC_CA_FILE" --request POST \
     -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     "${POLICY_API}/policies/${POLICY_ID}/deployments/${DEPLOYMENT_ID}/retry"
   

   An empty 204 response means Policy reset eligible retained work.

5. Read the operations list again. Check for a later attempt and a new error, then follow Data verification or Guardrails verification for the policy’s targets.

If Panel offers Retry publication or Retry archive, use the same safety checks. Do not use both the button and API request for the same attempt. An absent retry control does not authorize a manual bypass.

This endpoint requires no request body, If-Match, or general Idempotency-Key. A 409 can mean that automatic processing is still active or a later request exists. Read the operation list again before selecting another deployment identifier.

Correct Inputs and Seek Reapproval

Retry reuses retained deployment artifacts. It does not compile a corrected draft or incorporate later source configuration.

Complete the following steps:

1. Ask the policy author to correct rejected policy fields, or the integration administrator to correct the named connection setting.
2. Ask the PIM administrator to check whether the failed request created or changed any PIM objects. A timeout or error does not guarantee that PIM made no changes.
3. After the administrator resolves the previous request, follow the normal draft correction, submission, and approval journey. Policy can block reapproval while prior publication remains incomplete or uncertain.
4. Inspect the new governed revision and deployment after successful approval. Follow the Data or Guardrails verification guide linked above.

If approval reports pim-publication-incomplete, send the error and previous deploymentId to the PIM integration administrator. Do not repeatedly approve or delete the policy to clear this error. Refer to authoring and review troubleshooting for the current draft handoff.

Record Manual Archive Evidence

Use this path only for evidence tied to an active withdrawal. It requires policy:archive, not merely audit access.

Complete the following steps:

1. Copy deploymentId from the latest removal request in Operations or the operation-list response.
2. Ask the PIM or Traverse integration administrator for the location identifiers associated with that removal request. Do not submit evidence until the administrator supplies and checks those identifiers.
3. Prepare the ticket reference, description, and distinct location identifiers. Explain what the operator actually observed.
4. Submit POST /policies/{policy_id}/archive-evidence using the archive evidence contract. The request includes deploymentId, ticketReference, description, and locationIds.
5. Retain the returned event identifier and recording time. A 201 response records immutable audit evidence, not completed deprotection.
6. Follow withdrawal verification. Confirm that the policy finishes archiving. Recording manual evidence alone does not complete removal.

This evidence endpoint requires no general If-Match or idempotency key. It appends an event. Inspect an uncertain result before submitting duplicate evidence. A 409 can identify inactive withdrawal or unexpected locations. Stop if you cannot obtain the expected location scope.

Verification and Escalation

Read the latest operation again and check whether its error persists. For publication, follow the Data or Guardrails verification guide for the policy’s targets. For removal, follow withdrawal verification rather than treating an accepted archive request as completion.

If uncertainty remains, preserve the current generation and escalate. Do not claim recovery from approval, retry acceptance, or an evidence event alone.

Related: recovery reference and policy lifecycle tasks.

4 - Reconcile a Policy's Native Ownership

Use this task when publication reports missing or conflicting native ownership. Policy Integration Manager (PIM) identities differ from Policy’s saved reference keys. Do not repair a mismatch by guessing an identity from its name. A binding associates a saved Policy reference with a native object’s identifier. The ownership registry stores these associations. Its version changes independently of a draft or policy revision.

Prerequisites

Prepare the following:

• Identify the affected policy and operation.
• Obtain policy:system-configure for inspection and decisions.
• Obtain additional policy:archive authority if you intend to withdraw.
• Arrange an authorized integration owner for native inventory or configuration problems.
• Use the application programming interface (API) request setup.

An ordinary author should preserve the error and hand off this task. Policy ownership grants do not supply system-configuration authority.

Inspect the Policy Incident

Complete the following steps:

1. Read the current policy-scoped incident:

   curl --silent --show-error --include --cacert "$PPC_CA_FILE" \
     -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     "${POLICY_API}/policies/${POLICY_ID}/pim-reconciliations"
   

   The response provides unresolved bindings and the strong registry ETag.

2. Select the affected refKey from the returned incident. Keep its persisted native unique identifier (UID) distinct from the reference key.

3. Inspect the selected binding when needed. Set REF_KEY to the returned key:

   curl --silent --show-error --include --cacert "$PPC_CA_FILE" --get \
     -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     --data-urlencode "refKey=${REF_KEY}" \
     "${POLICY_API}/policies/${POLICY_ID}/pim-reconciliations"
   

4. Save the response and its ETag header in your incident record. The decision request needs its refKey, governedSetGeneration, candidate identifiers, and affected policy versions.

5. Ask the owners of the policies listed in the response to review the proposed adoption, replacement, or removal. Several policies can refer to the same PIM object.

A healthy original identity can return no allowed action. A 503 means inventory evidence remains unavailable. It cannot prove native absence. A 409 can mean that a policy changed after inspection or has no current approved publication to repair. Read the error message, then repeat inspection before preparing a decision.

Choose Only an Allowed Decision

The following table defines the decision boundary for each allowed action:

Make a decision only from the current inspection:

1. Select an action from the current allowedActions. Stop if inspection offers no suitable action.
2. Prepare its body using the reconciliation reference. Copy the response’s refKey and governedSetGeneration, then add the fields required for the selected action. State why you chose the candidate, replacement, or removal.
3. Attach the strong registry ETag as If-Match. Do not use a draft token or governed-policy token.
4. Assign an Idempotency-Key to this exact decision. Retain the key, body, resource, and precondition in the approved incident record.
5. Submit POST /policies/{policy_id}/pim-reconciliations. Adoption or replacement authorization returns 200. Withdrawal acceptance returns 202.
6. Read the policy-scoped inspection again. Confirm the reconciled identity or follow the returned withdrawal deployment.

Replacement authorization does not mean Policy already created a replacement. Withdrawal acceptance does not mean Policy already removed protection. Refer to publication and withdrawal recovery for subsequent operation verification and eligible retry.

Handle Races and Uncertain Results

Use the response to select the next inspection or handoff:

• For 428, supply the required registry precondition.
• For 400, obtain a valid strong registry token from inspection.
• For 412, inspect again because the registry changed.
• For 409, read the error message and repeat inspection. Compare the returned policies, candidate, and allowedActions with your request.
• For 503, ask the PIM administrator to restore inventory access, then repeat inspection.

After changed evidence, reconsider the decision before preparing a new request. Use a new key for a newly decided mutation. After a lost response, reuse a key only for the identical prior decision. Do not change its body or evidence while claiming an exact replay. If you cannot reconstruct the original request, ask the administrator handling the incident to inspect the current mapping before another submission.

Verification and Stop Conditions

Repeat the inspection request and check that the returned PIM identifier matches your decision. Then follow delivery verification for the affected policy. If PIM inventory is unavailable, an affected policy owner has not agreed, or allowedActions offers no suitable choice, escalate the incident.

For cross-policy stale saved mappings, use global cleanup instead. For an unresolved incident, use the diagnostic handoff.

5 - Remove Verified-Stale Ownership Mappings

Use this task for stale saved ownership mappings across policies. Cleanup removes Policy’s mapping, not a native Policy Integration Manager (PIM) object. For a current policy incident, start with policy ownership reconciliation. A binding maps a Policy reference key to a native object’s identifier. Stale means current, complete evidence proves the saved mapping no longer applies. Age alone does not establish that.

Prerequisites

Prepare the following:

• Obtain policy:system-configure for all operations in this task.
• Confirm complete live PIM inventory access with the integration owner.
• Use the application programming interface (API) request setup.
• Retain an approved incident reason and the exact selected evidence.

Do not use this task to bypass active publication or withdrawal. Do not delete native objects to make a cleanup decision succeed.

Enumerate One Saved Registry Version

Complete the following steps:

1. Request the first page:

   curl --silent --show-error --include --cacert "$PPC_CA_FILE" \
     -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     "${POLICY_API}/pim-reconciliations/bindings?limit=100&offset=0"
   

   Retain the strong ETag, target, ownership version, total, bindings, and nextOffset.

2. Set REGISTRY_ETAG to the exact first-page header value, including its quotes. Do not reconstruct it from another resource’s version.

3. Request each later page with that same token. Set OFFSET to the previous response’s non-null nextOffset:

   curl --silent --show-error --include --cacert "$PPC_CA_FILE" \
     -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     -H "If-Match: ${REGISTRY_ETAG}" \
     "${POLICY_API}/pim-reconciliations/bindings?limit=100&offset=${OFFSET}"
   

4. Continue until nextOffset becomes null. Confirm that the collected unique mappings match the reported total.

5. Restart from offset zero if any page returns 412. Discard the mixed-version listing rather than adding a new token midway.

A later-page 428 means the request omitted its required precondition. A 404 can mean the ownership registry does not exist. Enumeration lists saved reference keys and native unique identifiers (UIDs). It does not read native inventory or establish cleanup safety.

Inspect Selected Mappings

Inspect the selected mappings against live evidence:

1. Select only the saved keys relevant to the incident. Use up to 100 keys per inspection, not guessed native names.

2. Inspect the selected key. Set REF_KEY to an enumerated key:

   curl --silent --show-error --include --cacert "$PPC_CA_FILE" --get \
     -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     --data-urlencode "refKey=${REF_KEY}" \
     "${POLICY_API}/pim-reconciliations"
   

   For multiple keys, repeat the refKey query parameter.

3. Confirm that each selected mapping reports missing. Compare its persistedUid with your selected saved mapping.

4. Confirm that every selected blockingPolicyIds list is empty. Do not bypass active or unfinished policy work.

5. Confirm that writerPending is false. Retain the target, governedSetGeneration, ownership version, and this inspection’s registry ETag.

Stop on 503: unavailable inventory cannot prove native absence. Restore complete dependency access, then inspect again. Also stop for live identities, blocking policies, or a pending writer. Do not manually clear those blockers.

Forget Only the Verified Mappings

Complete the following steps:

1. Prepare forget_stale_bindings using the global decision contract. Include the inspected target, selected reference-to-UID mappings, reason, and governed-set generation.
2. Put the inspection’s strong registry ETag in If-Match. A draft or governed-policy validator cannot substitute for it.
3. Assign an Idempotency-Key to the exact decision. Retain the original request and key for uncertain-result recovery.
4. Submit POST /pim-reconciliations. A successful 200 response identifies the reconciliation, new ownership version, and forgotten mappings.
5. Enumerate the current registry again. Confirm that the selected mappings no longer appear.

For 409 or 412, inspect the changed registry and policy context again. Reconsider the decision before sending new evidence with a new key. After a lost response, replay only the identical original decision with its original key. Never reuse that key for different mappings, evidence, or intent.

Verification and Escalation

Match the returned forgotten mappings against the approved selection. Confirm their absence from a consistent current registry listing. Do not report native resource deletion: this operation does not perform it.

Stop when inventory, blockers, or current decision evidence remain uncertain. Use the diagnostic handoff instead of broadening the cleanup scope.

6 - Troubleshoot Automatic Recompilation

Use this task when changed source information does not produce expected approved output. Automatic recompilation periodically checks approved policies against fresh inputs. It differs from reviewer-requested saved validation and retained-deployment retry.

Prerequisites

Prepare the following:

• Identify the approved policy and the source change you expected it to reflect.
• Read automatic recompilation operations.
• Ask the platform operator to inspect effective scheduling and bounded logs.
• Use policy:audit only when operation inspection becomes necessary.

An author can report the policy, source change, and visible history. An author need not obtain cluster access or system-configuration authority.

Establish Whether a Cycle Should Run

Establish eligibility and effective scheduling first:

1. Confirm that the policy has an approved governed revision. Saving an unapproved draft does not place its proposed changes into this process.
2. Record the source change and its timestamp. Include the expected effect without assuming that every change alters compiled output.
3. Ask the operator to check the effective policy_recompile_interval_seconds setting. The default is 300 seconds. Nonpositive values disable scheduling.
4. Ask the operator to inspect cycle outcomes after the source change. Cycles wait before running, and execution adds time to the interval.

The interval is not a completion deadline or an immediate change-event trigger. Do not restart Policy to force a cycle. Policy exposes no public run-now endpoint for this task. Follow deployment change control before enabling a disabled schedule.

Choose the Matching Outcome

Use this table to match a recompilation outcome with the appropriate next action:

An input-refresh failure does not authorize compilation against cached discovery. Blocking cycles preserve the previous governed set. The governed set is the current governed policy content considered together during validation. Do not assume that a missing minor revision means that Policy ignored the schedule. Unchanged output intentionally creates neither a new version nor publication work.

Resolve the Cause and Observe the Next Cycle

Complete the following steps:

1. Preserve the cycle’s time, outcome, and sanitized diagnostics. Include the affected policy and effective settings in the incident record.
2. Send connection errors to the named integration’s administrator, or policy validation errors to the author and reviewer. Do not change author intent merely to clear an operational failure.
3. Observe the next scheduled cycle after correction. Use its actual outcome rather than assuming success after a fixed wait.
4. Inspect permitted policy history for changed compilation output. Automatic recompilation preserves authored intent, approval identity, and open drafts.
5. Inspect subsequent publication separately when output changes. A compilation minor and queued work do not prove protection.

If intended policy content must change, use the normal authoring and governance journey. Deployment retry sends retained artifacts. It does not request automatic recompilation. Legacy adoption or blocked delivery can require separate authorized decisions. Do not promise that another cycle will resolve them automatically.

Verification and Stop Conditions

For unchanged output, confirm a successful cycle using fresh inputs. For changed output, confirm the new compilation minor and associated publication work. Then follow the Data or Guardrails verification guide.

Stop and escalate when repeated cycles fail, the outcome remains unavailable, or a required action exceeds your authority. Include effective scheduling, observed outcomes, and the dependency owner’s findings.

7 - Common Policy Errors

Use the action and response together when identifying an error. Keep application programming interface (API) response details with your incident evidence. The same status code can describe different problems. Keep returned details and support references before attempting recovery.

Find the Matching Symptom

A member source is a directory or identity source configured in Policy Integration Manager (PIM). Its connection metadata differs from Policy’s own service login or a human user’s token.

Use this table to match an error symptom or response with its interpretation and next task:

Configuration errors can require an administrator or a dependency owner. Restricted diagnostic access does not imply permission to change that dependency. Refer to diagnostics for the handoff.

Verifying the Common Errors

Verify the outcome of the failed task, not merely service health.

Use these checks to confirm the task’s result:

• Reload the draft and check saved content and status after a correction.
• Check the new approved version in Change History and its delivery request in Operations after approval.
• Follow the Data or Guardrails verification guide after publication recovery.
• Check saved mappings after ownership repair or cleanup.
• Check routing and readiness separately after platform recovery.

Liveness and readiness checks cannot prove policy publication or target protection. Use the relevant playbook’s verification before closing the incident.

8 - Collect Policy Diagnostics

Collect enough evidence to identify the failed task and responsible operator. Start with information you can access. Do not request broad administrator access merely to report an issue.

Prerequisites

Prepare the following:

• Use your own supported Policy session or application programming interface (API) credentials.
• Obtain policy:audit only when your assigned investigation requires restricted diagnostics.
• Obtain namespace read access only for the optional platform checks.
• Follow your organization’s incident process for sensitive evidence.

Steps

Collect evidence available without cluster access:

1. Record the failed action and its timestamp with time zone. Include the configured Policy address and release version when known.
2. Retain the response status and sanitized error details. Capture a support reference if the response includes one.
3. Open the affected policy in Policy Library, or read it through GET /policies/{policy_id}. Record the policy identifier, displayed version, draft status, and protection status.
4. Record the last successful action. Include relevant source changes and the time the problem started.
5. Route the evidence to the matching troubleshooting task. Stop if its next step requires authority you lack.

Do not send bearer tokens, cookies, passwords, private keys, or rejected sensitive values. Remove authentication headers from captured requests before sharing them.

Inspect Restricted Evidence

An authorized auditor can inspect operations and validation diagnostics. Run the examples in Bash. Complete the endpoint, trusted certificate authority (CA), and token setup in Configure API access. This setup does not require cluster access. Use your own token, not a worker account or another participant’s token. Keep the protected header file in that setup’s dedicated shell. Follow its credential cleanup when you finish. Set the API alias and affected policy identifier before the first request:

export POLICY_API="${POLICY_BASE_URL:?Complete endpoint setup}"
export PPC_CA_FILE="${PPC_CA_FILE:?Set the trusted CA bundle path}"
export POLICY_ID='replace-with-the-affected-policy-identifier'

POLICY_API and the operations guide’s POLICY_BASE_URL identify the same versioned API base. Keep response headers when using these read-only requests:

curl --silent --show-error --include --cacert "$PPC_CA_FILE" \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/policies/${POLICY_ID}/operations"

Complete the following steps:

1. Save the operation-list response in your incident record after removing sensitive values.

2. Select the entry with the largest generation number. Record its deploymentId, lastError, attemptCount, and diagnostics. These identify the latest delivery request and its failure.

3. Retrieve retained validation evidence when you have a VAL- support reference. Set SUPPORT_REFERENCE to that exact reference:

   curl --silent --show-error --include --cacert "$PPC_CA_FILE" \
     -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
     "${POLICY_API}/validation-diagnostics/${SUPPORT_REFERENCE}"
   

4. Retain only the evidence needed for the incident. Successful diagnostic responses specify Cache-Control: no-store. Use approved incident storage.

Validation diagnostics expire after seven days. A 404 can mean absent or expired evidence. An operations 404 can mean no recorded deployments, not a missing policy. A 403 requires an authorized handoff, not a different endpoint.

Publication diagnostics can contain PUB- support references. Do not send these references to the validation-diagnostics endpoint. An operator with server access can correlate them with publication logs. An API-only caller should pass the reference to that operator.

Collect Optional Platform Evidence

Only a platform operator with namespace read access should run these commands. Replace pty-policy if your installation uses another namespace. Set and confirm the intended cluster context first:

export CTX='your-approved-kubernetes-context'
kubectl --context "${CTX:?Set CTX to the approved context}" cluster-info

Stop if the reported cluster differs from the incident’s deployment.

Collect only the platform evidence relevant to the incident:

1. List workload status and recent events.

   kubectl --context "${CTX:?Set CTX}" get pods,svc,events -n pty-policy
   

2. Inspect an affected pod from that list. Replace POD_NAME with its exact name:

   kubectl --context "${CTX:?Set CTX}" describe pod POD_NAME -n pty-policy
   

3. Read bounded logs from that pod.

   kubectl --context "${CTX:?Set CTX}" logs POD_NAME -n pty-policy --since=15m --tail=200
   

Review logs for secrets before attaching excerpts. Do not collect Secret contents or query the database as a routine diagnostic. Check previous-container logs only when the pod history requires them.

Prepare an Escalation

Provide the responsible administrator or your organization’s support contact with:

• The failed task, timestamp, time zone, status code, and sanitized message.
• The policy, draft, governed revision, deployment, and generation identifiers you can access.
• The support reference and authorized diagnostic result, including expiry or access refusal.
• The current state and last successful action.
• The selected playbook, actions already attempted, and observed results.
• The missing authority or evidence that prevents safe progress.

If a reconciliation request lost its response, include its request body and idempotency key after removing sensitive values. Keep that information in the approved incident record, not public logs. Ask the administrator handling reconciliation to check the current mapping before submitting another decision.

Verification

Confirm that the recipient can identify the failed task and next authorized action. Missing cluster access or expired diagnostics does not invalidate the report. Record those limits and preserve the original public error.

9 - Recover Policy Safely

Use this directory to select a recovery task. Each linked playbook identifies the required authority and completion evidence. Application programming interface (API) requests require the command’s specific authority. Do not substitute a deployment retry for a corrected policy approval. Do not substitute a Helm rollback for database recovery. Retry continues retained delivery work. Reconciliation compares saved ownership or protection evidence with current observations. Database recovery restores retained local state and still requires checking external effects.

Escalation Data to Collect

Retain the failed action, timestamp, policy identifier, and sanitized response. Include deployment and generation identifiers when available. Refer to diagnostics and escalation to collect evidence within your access. Cluster access is not a prerequisite for reporting a policy failure.

Recover From Failed Release Change

Stop before rolling back workloads against a changed database schema or owner. Helm rollback does not reverse database schema or ownership changes. An older chart might expect credentials that no longer own the database.

Refer to installation and release-change triage. Use the administrator’s qualified deployment or restore procedure. Keep PostgreSQL inside the Policy stack.

Recover From a Partially Failed Policy Deployment

A failed publication might already have changed native resources. Do not delete ownership records or assume that failure means no effect. Refer to publication and withdrawal recovery. That playbook separates retained-artifact retry from corrected-draft reapproval.

Resolve a Missing PIM Ownership Binding

Policy Integration Manager (PIM) bindings connect saved references to native identities. Only a caller with policy:system-configure can inspect and reconcile them. Refer to policy ownership reconciliation. Use only actions that the current inspection permits.

Forget a Verified-Stale PIM Ownership Mapping

Global cleanup removes saved mappings, not native objects. It requires complete inventory evidence and no blocking work. Refer to verified-stale binding cleanup. An unavailable inventory cannot prove native absence.

Recover API Routing

Refer to installation, identity, and routing troubleshooting. Check configured public paths and gateway acceptance before changing chart values. Do not disable authentication or certificate verification as a repair.

Recover a Stalled Publication or Withdrawal

Refer to publication and withdrawal recovery. Retry only eligible current-generation work after resolving its cause. Record manual archive evidence separately from observed deprotection.

For changes that never produced publication work, use automatic recompilation troubleshooting.

10 - Troubleshoot Installation, Identity, and Routing

Use this task when Policy cannot start, authenticate callers, or serve configured paths. Separate platform availability from policy delivery failures. Healthy workloads do not establish protection for an approved policy.

Prerequisites

Prepare the following:

• Obtain the configured Policy address and installed release details.
• Use your own supported gateway session or application programming interface (API) credentials.
• Involve a platform operator for namespace, release, gateway, and log inspection.
• Follow diagnostics before changing configuration.

For cluster inspection, have the platform operator complete the explicit context setup. Every cluster example below requires that approved CTX value.

Use the installation instructions and configuration reference for canonical settings. Do not copy development credentials or registry overrides into a customer installation.

Recover From a Failed Installation or Release Change

Complete these steps:

1. Ask the operator to inspect the installed release history. Replace the release and namespace if your deployment uses different names:

   helm --kube-context "${CTX:?Set CTX}" history policy -n pty-policy
   

2. Identify the first failing workload or initialization task. Use pod status, events, and bounded logs from the failed interval.

3. Check database bootstrap and runtime configuration through the authorized operator. Keep PostgreSQL inside the Policy stack.

4. Ask the operator to verify Secret references and required key names. Do not print or attach credential values.

5. Determine whether the release change altered database schema, grants, or ownership. Preserve this evidence before selecting a recovery procedure.

6. Ask the platform and database administrators for the deployment or restore procedure tested with the selected release versions. Do not restart an older API until they confirm that it can use the current database schema and accounts.

Helm rollback does not reverse database schema or ownership changes. An older chart might expect a former shared database login. Do not blindly roll back workloads after a database-role migration. Database recovery also requires reconciliation of external effects before resuming work. These checks do not establish a universal supported rollback or restore recipe.

Resolve Authentication and Permission Failures

Check authentication, command authority, and dependency access separately:

1. Record the failing route, action, and status code. Separate failed authentication from a refused policy command.
2. Reauthenticate through the supported gateway for a 401 response. Do not inject trusted identity headers or bypass the gateway.
3. Check the command capability for a 403 response. Ask a Protegrity Provisioned Cluster (PPC) user with administrator permissions to check the required capability against your account’s role mapping.
4. Check applicable policy resource grants for edit or rollback work. Ask an existing owner to resolve grant issues.
5. For a Policy Integration Manager (PIM) or Traverse login failure, ask that product’s administrator to check the account used by the failing request. Policy authority does not establish native integration permissions.

Do not grant broad administrator access as a routine repair. An owner/editor grant does not create approval, audit, or system-configuration capability. For draft decisions, use authoring and review troubleshooting.

Distinguish Credential Kinds

Your gateway login authenticates interactive requests. Your draft, governed-policy, and registry validators protect resource versions. An idempotency key identifies an exact reconciliation decision. None of these keys replaces authentication.

Interactive dependency calls and unattended workers can use different credentials. A caller’s delegated bearer token does not repair a worker’s configured service identity. A workload service identity does not grant an interactive user native permissions. Kubernetes ServiceAccounts, registry pull credentials, and dependency users serve different purposes.

Ask the PIM or Traverse administrator to verify the service user for worker failures, or your own dependency access for interactive failures. Do not copy worker credentials into user requests or share another user’s token. Refer to API authentication.

Diagnose Public Routing

Compare the public route with the configured deployment:

1. Confirm the configured host and versioned API base with the administrator. Do not assume a 404 means the policy itself is missing.

2. Compare the failing public path with the installed configuration. The usual API prefix is /pty/policy/v1.0.

3. Ask the operator to inspect gateway routes. For the default namespace:

   kubectl --context "${CTX:?Set CTX}" get httproute -n pty-policy
   

4. Ask the operator to inspect the affected route’s acceptance and backend references. Use the actual gateway name and namespace from that route.

5. Ask the operator to verify backend Service endpoints and ports. Correct the installed route configuration through approved change control.

6. Retest the configured Panel path and a known API path independently. The usual Panel path ends in /pty/policy/v1.0/ui/, not the host root.

Do not reapply chart values merely because a route is missing. Confirm whether this installation uses Gateway API routing first. Do not disable authentication or certificate validation to make a probe succeed.

Check Service Health Without Claiming Policy Recovery

Set POLICY_API, PPC_CA_FILE, and the protected POLICY_AUTH_HEADER file using the diagnostic setup. Use your deployment’s required authentication:

curl --silent --show-error --include --cacert "$PPC_CA_FILE" \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/live"
curl --silent --show-error --include --cacert "$PPC_CA_FILE" \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/ready"

Liveness normally returns 204. Readiness returns 204 when its checks succeed. 503 needs dependency investigation. These checks do not validate approval, publication, target activation, or deprotection.

Check Shared Identity Provider Metadata

The shared identity provider (IdP) connection document supports native member-source creation. It is not the Traverse poller’s login Secret. When Policy follows an existing Traverse installation, the shared document might remain empty. Use the reported workaround and ask the connection owner to verify the intended entry. Do not grant extra scanner permissions or replace working service credentials to conceal missing metadata.

Verification and Escalation

Confirm workload stability, supported authentication, route acceptance, and the original failing request. After deployment recovery, repeat installation verification. Then follow the delivery guide for affected policies.

Stop when database compatibility, trusted identity, or route ownership remains uncertain. Use the diagnostic handoff with the installed release, failing path, timestamps, and sanitized operator findings.