> For the complete documentation index, see [llms.txt](https://docs.docontrol.io/docontrol-user-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.docontrol.io/docontrol-user-guide/workflows/workflow-error-references.md).
# Workflow error references
The following content maps every error and reason message shown in the UI to its root cause in Google Drive, and the recommended remediation step.
* **Workflow actions** — **Remove Collaborator** and **Remove Sharing Links**
* **Assessment reports** — Inventory remediation assessment reasons (why an asset/permission is marked **INVALID** and cannot be auto-remediated)
Status key
* **FAILURE** — the action could not complete; user must take corrective action.
* **WARNING** — the action was skipped due to an expected condition (file deleted, permission already gone, inherited externally); no urgent action required.
* **dynamic** — the message contains runtime values such as a collaborator email or asset ID substituted at execution time.
***
### Integration & Auth Errors
#### *"Your Google integration does not have the necessary Write permissions to perform this action."*
| **Field** | **Value** |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | FAILURE |
| **What it means in Google Drive** | The DoControl service account was set up with read-only OAuth scopes. Google Drive requires an explicit write scope to modify file permissions or sharing settings. |
| **What to do next** | Go to Integrations > Google Drive > Edit integration settings > Scopes and enable the Write scope. Then retry the workflow. |
| **Source** | INTEGRATION\_MISSING\_WRITE\_PERMISSIONS\_ERROR |
#### *"There was an error with the Google Drive integration. Go to the Integrations page, disconnect the Google Drive integration, and then reconnect it."*
| **Field** | Value |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | FAILURE |
| **What it means in Google Drive** | The OAuth refresh token that DoControl holds for your Google Workspace has expired, been revoked, or become invalid. Google returns 400 invalid\_grant. This happens when an admin revokes access or the token lifetime expires. |
| **What to do next** | Disconnect and reconnect the Google Drive integration from the Integrations page to issue a fresh token. |
| **Source** | INTEGRATION\_ERROR\_MESSAGE / 400 invalid\_grant |
#### *"The Google Drive integration doesn't have the right permissions to complete this action. Go to the Integrations page. From the Google Drive integration, click the gear icon > Edit integration settings > Scopes (3), and check the Write box."*
| **Field** | Value |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Status** | FAILURE |
| **What it means in Google Drive** | Google returned 401 Unauthorized unrelated to a specific user being archived. The integration token is valid but lacks the required Drive API write scopes, so Google refuses the request. |
| **What to do next** | Edit the integration settings and enable the Write scope (Scopes step 3). Reconnect if the scope change does not take effect. |
| **Source** | PERMISSIONS\_ERROR\_MESSAGE / 401 general |
***
### User / Owner Account Errors
#### *"User is either archived or does not have an active Drive license."*
| **Field** | Value |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | FAILURE |
| **What it means in Google Drive** | Google returned 401 with the internal message "Active session is invalid. Error code: 4". This specific code means the user account DoControl is impersonating (the file owner) has been suspended or archived in Google Workspace, or their Google Drive license has been removed. |
| **What to do next** | Check the file owner's account status in Google Workspace Admin. Restore the account or reassign the file to an active owner, then retry. |
| **Source** | USER\_ARCHIVED\_OR\_NO\_LICENSE\_ERR\_MESSAGE / 401 "Active session is invalid. Error code: 4" |
#### *"No user with sufficient permission role (File Organizer or higher) was found on the shared drive to perform this action. Please ensure at least one user has File Organizer or Organizer role on the shared drive."*
| **Field** | **Value** |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | FAILURE |
| **What it means in Google Drive** | This file lives in a Shared Drive. DoControl must impersonate a user who has at least the File Organizer role on that drive to modify permissions. No such user was found during the owner lookup step. |
| **What to do next** | In Google Drive, open the Shared Drive > Manage members, and promote at least one internal user to File Organizer or Organizer. Then retry the workflow. |
| **Source** | INSUFFICIENT\_PERMISSION\_ROLE\_ERR\_MESSAGE |
#### *"Couldn't generate access token for any of the asset owners to perform the API request."*
| **Field** | **Value** |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Status** | FAILURE |
| **What it means in Google Drive** | DoControl could not obtain a valid impersonation token for any of the known owners of this file. All owner accounts are likely suspended, deleted, or have lost their Drive license. |
| **What to do next** | Verify the file still has at least one active owner with a Drive license in Google Workspace Admin. If the file is orphaned, reassign ownership before retrying. |
| **Source** | ASSET\_OWNER\_NOT\_FOUND\_ERR\_MESSAGE |
***
### File Not Found
#### *"The asset wasn't found. It may have been deleted by a previous workflow execution, or the wrong asset ID may have been entered in the workflow."*
| **Field** | **Value** |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | WARNING |
| **What it means in Google Drive** | Google Drive returned 404 Not Found for this file ID. The file does not exist at the time the action ran — it was already deleted by a prior DoControl workflow run, by the file owner, or by a retention policy. |
| **What to do next** | No action required. The file is gone. If deletion was unexpected, check Google Drive audit logs to find who deleted it and when. |
| **Source** | ASSET\_NOT\_FOUND\_ERR\_MESSAGE / 404 |
***
### Inherited Permission Errors
#### *"Cannot remediate shared drive Inherited permissions. to remediate this file, use our inventory remediation actions."*
| **Field** | **Value** |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | FAILURE |
| **What it means in Google Drive** | This file is in a Shared Drive and its permission is inherited from the drive itself, not granted directly on the file. Google's API returns 403 — you cannot remove a drive-level permission from a single file. |
| **What to do next** | Use DoControl's Inventory remediation actions to address the permission at the Shared Drive level, rather than at the individual file level. |
| **Source** | CANNOT\_REMEDIATE\_SHARED\_DRIVE\_INHERITED\_PERMISSIONS\_ERR\_MESSAGE / 403 Shared Drive inherited |
#### *"This permission is inherited from a parent folder. Remove the collaborator on that folder, or use Google limited access for this item where the API allows."*
| **Field** | **Value** |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | FAILURE |
| **What it means in Google Drive** | Google's API returned reason cannotDeletePermission or a message indicating the permission is inherited. The collaborator's access comes from a parent folder in My Drive, not a direct grant on this file. The Drive API does not allow deleting inherited permissions on a child item. |
| **What to do next** | Navigate to the parent folder in Google Drive and remove the collaborator there. Alternatively, use "Restricted" link settings on the file itself to limit further sharing. |
| **Source** | CANNOT\_DELETE\_INHERITED\_DRIVE\_PERMISSION\_ERR\_MESSAGE / 403 cannotDeletePermission |
#### *"This permission is inherited from a folder outside your organization or a restricted location we cannot access."*
Also appears as:
***"This permission is inherited from a folder outside your organization or a restricted location we cannot access. Parent owner - \"***
| **Field** | **Value** |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | WARNING |
| **What it means in Google Drive** | The file owner is outside your company domain, or the permission traces back to a folder that DoControl cannot access (e.g., a shared folder from an external Google Workspace). DoControl can only impersonate users within your organization. |
| **What to do next** | Manual review required. The sharing originates from outside your organization. Contact the external owner or adjust Google Workspace sharing policies to prevent external folder-level sharing. |
| **Source** | INHERITED\_FROM\_OUTSIDE\_ORG\_ERR\_MESSAGE (dynamic: + "Parent owner - ") |
#### *"Asset permission is inherited from a parent folder. cannot remove \[collaborator] directly. Asset ID: \[assetId] (dynamic)"*
| **Field** | **Value** |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Status** | WARNING |
| **Dynamic values** | \[collaborator] = collaborator email address; \[assetId] = the parent folder's asset ID |
| **What it means in Google Drive** | DoControl walked the folder hierarchy and found that this collaborator's access was granted on a parent folder (the parent asset ID is shown in the message). The permission cannot be removed from the child file — it must be removed at the parent. |
| **What to do next** | Use the parent asset ID shown in the message to locate the parent folder and remove the collaborator there. DoControl may be able to re-run remediation on that parent folder. |
| **Source** | removeCollaborator.ts — inline (resolved parent folder) |
***
### Permission Already Removed
#### *"\[collaborator] was not found on asset \[assetId]. Permission might have been removed during this execution. (dynamic)"*
| **Field** | **Value** |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | WARNING |
| **Dynamic values** | \[collaborator] = collaborator email; \[assetId] = file asset ID |
| **What it means in Google Drive** | When DoControl listed the file's permissions, the collaborator's email was not present. The permission was already removed — by the file owner, another workflow run, or manually before this action ran. |
| **What to do next** | No action needed. The collaborator no longer has access. This is an informational warning. |
| **Source** | removeCollaborator.ts — inline (collaborator not found in permission list) |
***
### **Insufficient Operational Permissions**
#### *"The user does not have sufficient permissions to remove collaborators from this file."*
| **Field** | **Value** |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Status** | FAILURE |
| **What it means in Google Drive** | Google returned 403 with a message containing "sufficient permissions". The user DoControl impersonated authenticated successfully but does not have the Drive role required to modify permissions on this file (e.g., they are only a Viewer or Commenter). |
| **What to do next** | Verify the file owner has at least Editor access on the file. If the file is in a Shared Drive, confirm they have File Organizer or Organizer role. |
| **Source** | removeCollaborator.ts — inline (403 "sufficient permissions") |
***
### Rate Limiting
#### *"You exceeded your Google account rate limit. Try again in 15 minutes."*
| **Field** | **Value** |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | FAILURE |
| **What it means in Google Drive** | Google Drive API returned 403 "Limit Exceeded". Your Google Workspace has hit the per-user or per-project quota for Drive API write operations. This is a temporary throttle, not a permissions problem. |
| **What to do next** | Wait at least 15 minutes and retry. If this happens frequently, contact Google Workspace support to request a quota increase, or review how many concurrent DoControl workflows are running against Drive simultaneously. |
| **Source** | RATE\_LIMIT\_EXCEEDED\_MESSAGE / 403 Limit Exceeded |
***
### Assessment Report Reasons
These messages appear in **Inventory remediation assessment reports** when DoControl marks an asset/permission as **INVALID**. Unlike workflow errors, these are detected during assessment (before remediation runs) — typically when DoControl cannot resolve where an inherited My Drive permission comes from.
Assessment status key
* **INVALID** — the permission cannot be remediated automatically; manual review or corrective action is required.
* **INHERITED** — the permission is inherited but DoControl successfully resolved the parent folder (inheritId is set).
* **dynamic** — the message may include a parent owner email substituted at assessment time.
#### *"This permission is inherited from an ancestor folder that no longer exists or is unreachable."*
| **Field** | **Value** |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | INVALID |
| **What it means in Google Drive** | The collaborator's access on this My Drive file/folder is inherited, not granted directly. DoControl can see the permission on the asset itself, but cannot reach the parent folder chain needed to remove it. This usually happens when the impersonated user (typically the file owner) has access to the asset but lacks at least Reader permission on its parent folder. Without read access to the parent, Google Drive's files.get (file metadata) API returns no parents field for the asset — even though the inherited permission is still visible on the file. DoControl detects this in two ways: (1) Initial assessment — permission is inherited-only on a My Drive asset and parents is empty in the exported metadata (isMyDriveInheritedAndUnreachable). (2) Parent-chain resolution (BFS) — DoControl walks up the folder tree but hits a dead end: a folder whose owner is in your organization, yet that folder also has no accessible parent (in-org orphan). |
| **What to do next** | Manual review required. Identify the parent folder that originally granted this access and either grant the file owner (or DoControl's impersonation user) at least Reader access on the parent folder so the chain can be resolved, or remove the collaborator directly on the parent folder if you can locate it in Google Drive. If the parent was deleted or ownership changed, the inherited permission may be a stale orphan — consider revoking access manually on the child asset if Google allows it, or reassigning file ownership. |
| Source | IN\_ORG\_ORPHAN\_INHERITED\_REASON · isMyDriveInheritedAndUnreachable · resolveMyDriveInheritedService.ts |
#### *"This permission is inherited from a folder outside your organization or a restricted location we cannot access."*
Also appears as: This permission is inherited from a folder outside your organization or a restricted location we cannot access. Parent owner: \
| **Field** | **Value** |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | INVALID |
| **What it means in Google Drive** | During assessment parent-chain resolution, DoControl traced the inherited permission to a folder whose owner is outside your company domain, or to a location DoControl cannot impersonate (external Google account, restricted shared folder, etc.). DoControl can only act as users within your organization. |
| **What to do next** | Manual review required. Contact the external parent owner shown in the message (if present), or adjust Google Workspace sharing policies to prevent external folder-level sharing. The collaborator must be removed at the external source folder. |
| **Source** | OUTSIDE\_ORG\_INHERITED\_REASON\_BASE · buildOutsideOrgInheritedReason · resolveMyDriveInheritedService.ts |
#### *"The permission is no longer present on the source folder. It may have been removed or moved."*
| **Field** | **Value** |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | INVALID |
| **What it means in Google Drive** | DoControl resolved the parent folder in the inheritance chain, but when it re-checked that folder's permissions, the collaborator's permission ID was no longer listed. The permission may have been removed, the folder moved, or permissions changed between export and assessment resolution (permission drift). |
| **What to do next** | Re-run the assessment to get fresh data. If the permission still appears on the child asset in Google Drive but not on the parent, the inheritance chain may have changed — verify manually in Google Drive whether the collaborator still has access. |
| **Source** | PERM\_NO\_LONGER\_ON\_SOURCE\_REASON · resolveMyDriveInheritedService.ts (cause: perm\_not\_on\_parent) |
#### *"This user is archived. To remediate, you should unarchive the user and remediate again."*
| **Field** | **Value** |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status** | INVALID |
| **What it means in Google Drive** | The file owner associated with this remediation row is archived in Google Workspace. DoControl cannot impersonate archived users to perform Drive API operations on their My Drive files. |
| **What to do next** | Unarchive the user in Google Workspace Admin, then re-run the assessment and remediation. Alternatively, transfer file ownership to an active user first. |
| **Source** | validateUsers · assessmentService.ts |
***
Derived from: removeCollaborator.ts · removeSharingLinks.ts · userErrorsCheck.ts · contstants.ts · integrationValidation/index.ts · assessmentService.ts · resolveMyDriveInheritedService.ts
Source Notion page:
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.docontrol.io/docontrol-user-guide/workflows/workflow-error-references.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.