Troubleshoot permission error messages

This document covers the error messages that you might encounter if you don't have the required access permissions for a resource and describes how you can resolve these errors.

Permission error messages

The Google Cloud console, Google Cloud CLI, and REST API all display error messages when you try to access a resource that you don't have permission to access.

These error messages can be caused by any of the following:

  • There's a deny policy blocking access. If a deny policy prevents you from using any of the required permissions, then Google Cloud displays an error message.
  • You aren't eligible to access the resource. If you're subject to any principal access boundary policies, then the resource that you're trying to access must be included in the policies' principal access boundary rules. If it isn't, then Google Cloud displays an error message.
  • The resource doesn't exist. If the resource doesn't exist, then Google Cloud displays an error message.

The following sections show what these error messages look like for the Google Cloud console, gcloud CLI, and REST API.

Google Cloud console error messages

In the Google Cloud console, error messages look similar to the following:

These error messages contain the following information:

  • The resource that you tried to access: The resource name appears in the title of the error page and indicates the resource that you were trying to access when you encountered the permission error.
  • The missing required permissions: A list of the permissions that you need to have to access the resource.

  • A list of Privileged Access Manager entitlements with roles that contain the required permissions: This list is non-exhaustive—it contains only the top entitlements that Google Cloud suggests to resolve the access issue.

    This list is only available for permission errors that can be resolved by updating granting additional IAM roles.

    You can click an entitlement to learn more about the entitlement and to request a grant against the entitlement. To learn more, see Request a Privileged Access Manager access grant in this document.

    If no entitlements contain the required permissions, then the error message page doesn't include the list of entitlements.

  • A list of IAM roles that contain the required permissions: This list is non-exhaustive—it contains a curated list of roles that Google Cloud suggests to resolve the access issue. Ordering is based on the type of actions permitted by the role, service relevance, and the number of permissions.

    If you have the permissions required to grant roles, then this section is titled Select a role to grant. If you don't have the required permissions, then this section is titled Request a specific role.

    This list is only available for permission errors that can be resolved by granting additional IAM roles.

    You can click a role to learn more about the role and request that the role be granted to you. If you have the permissions required to grant roles, then you can grant yourself the role instead of requesting it.

Google Cloud CLI and REST API error messages

The exact wording of the error message depends on the command that you run. However, it typically contains the following information:

  • The required permission
  • The resource you tried to perform an action on
  • The authenticating account

For example, if you don't have permission to list buckets in a project, you see an error message like the following:

gcloud

ERROR: (gcloud.storage.buckets.list) HTTPError 403:
EMAIL_ADDRESS does not have
storage.buckets.list access to the Google Cloud project. Permission
'storage.buckets.list' denied on resource (or it may not exist). This command
is authenticated as EMAIL ADDRESS which
is the active account specified by the [core/account] property.

REST

{
  "error": {
    "code": 403,
    "message": "EMAIL ADDRESS does not have storage.buckets.list access to the Google Cloud project. Permission 'storage.buckets.list' denied on resource (or it may not exist).",
    "errors": [
      {
        "message": "EMAIL ADDRESS does not have storage.buckets.list access to the Google Cloud project. Permission 'storage.buckets.list' denied on resource (or it may not exist).",
        "domain": "global",
        "reason": "forbidden"
      }
    ]
  }
}

Request missing permissions

If you don't have permission to modify access-related policies in your organization, then you can't resolve the permission errors on your own. However, you can send an administrator an access request using the context from the error message.

You can request access in the following ways:

If you're using the Google Cloud console and you have permissions required to grant roles, then you can grant yourself the role directly from the error message instead of requesting it. For more information, see Self-grant a role in the Google Cloud console.

Request the required permissions

To request the required permissions, do the following:

Console

  1. In the list of missing permissions, click Request permissions.

  2. In the Request Access panel, choose how you want to notify your administrator:

    • If your organization supports Essential Contacts, then you can send an auto-generated email to your organization's technical Essential Contact. To send this email, do the following:

      1. Select Send auto-generated email.
      2. Add any context about the request that you want to include.
      3. Click Send request.

    • To copy the access request and paste it into your preferred request management system, do the following:

      1. If your organization supports Essential Contacts but you want to send the notification manually, select Notify manually.
      2. Add any context about the request that you want to include.
      3. Click Copy message.
      4. Paste the request into your preferred request management system.

      Your administrator receives your access request, along with any additional context that you provided.

gcloud

Copy the list of missing permissions from the error message, then use your preferred request management system to ask an administrator to give you these permissions.

REST

Copy the list of missing permissions from the error message, then use your preferred request management system to ask an administrator to give you these permissions.

Request a grant against a Privileged Access Manager entitlement

Privileged Access Manager entitlements define a set of IAM roles that you can request at any time. If your request is successful, then you're granted the requested roles temporarily.

This resolution option is only available if the permission error is due to your allow policies and if you have a Privileged Access Manager entitlement with the required permissions.

To request a grant against an existing entitlement, do the following:

Console

  1. When you encounter an error message, find the Request temporary access section. This section lists all of the Privileged Access Manager entitlements that contain a role with the required permissions.

    If no Request temporary access section is returned, then no entitlements contain the required permission. In this case, you can ask an administrator to create a new entitlement.

  2. Review the list of available entitlements and select the entitlement that you want to request a grant against.

  3. Click the entitlement, then click Request access.

  4. In the Request grant panel, enter the details for the request grant:

    • The duration required for the grant, up to the maximum duration set on the entitlement.

    • If required, a justification for the grant.

    • Optional: The email addresses to notify of the grant request. Google identities that are associated with approvers are automatically notified. However, you might want to notify a different set of email addresses, especially if you're using Workforce Identity Federation.

  5. Click Request grant.

  6. To see your grant history including approval statuses, go to the Privileged Access Manager page in the Google Cloud console, then click Grants > My grants.

gcloud

  1. Search for available entitlements to find an entitlement with a role that has the required permissions.

    If no entitlement is returned, then you can ask an administrator to create a new entitlement.

  2. Request a grant against the entitlement.

  3. Optional: Check your grant request status.

REST

  1. Search for available entitlements to find an entitlement with a role that has the required permissions.

    If no entitlement is returned, then you can ask an administrator to create a new entitlement.

  2. Request a grant against the entitlement.

  3. Optional: Check your grant request status.

Request a role

If the permission error is due to an allow policy, then you can request that an administrator grant you a role with the required permissions to resolve the error.

If the error is due to a different policy type or if you aren't sure which policy type is causing the error, then request the required permissions instead.

Console

  1. In the Request a specific role section, review the list of recommended roles and choose the one that you want to request. You can click the roles to view more details about them. This section is only visible if the permission error is due to an allow policy.

  2. Click the role that you've chosen, then click Request role.

  3. In the Request Access panel, choose one of the options for notifying your administrator:

    • If your organization supports Essential contacts, then you can send an auto-generated email to your organization's technical Essential Contact. To send this email, do the following:

      1. Select Send auto-generated email.
      2. Add any context about the request that you want to include.
      3. Click Send request.

    • To copy the access request and paste it into your preferred request management system, do the following:

      1. If your organization supports Essential Contacts but you want to send the notification manually, select Notify manually.
      2. Add any context about the request that you want to include.
      3. Click Copy message.
      4. Paste the request into your preferred request management system.

    Your administrator receives your access request, along with any additional context that you provided.

gcloud

  1. Identify an IAM role that contains the missing permissions.

    To see all of the roles that a given permission is included in, search for the permission in the IAM roles and permissions index, then click the permission name.

    If no predefined roles match your use case, then you can create a custom role instead.

  2. Use your preferred request management system to request that an administrator grant you the role.

REST

  1. Identify an IAM role that contains the missing permissions.

    To see all of the roles that a given permission is included in, search for the permission in the IAM roles and permissions index, then click the permission name.

    If no predefined roles match your use case, then you can create a custom role instead.

  2. Use your preferred request management system to request that an administrator grant you the role.

Self-grant a role in the Google Cloud console

If you encounter a permission error in the Google Cloud console and you have the permissions required to grant roles, then you can grant yourself a role directly from the permission error message:

  1. In the Select a role to grant section, review the list of recommended roles and choose the one that you want to request. You can click the roles to view more details about them.

  2. To grant the role that you've chosen, click the role, then click Grant access.

Resolve permission errors from access requests

If you're an administrator, then you might receive access requests from users who have encountered permission errors in the Google Cloud console. These requests are typically sent to the following people:

  • Your organization's technical Essential Contact. If your organization has enabled essential contacts, then users who encounter permission errors in the Google Cloud console have the option to send an access request to their organization's technical Essential Contact.

  • Contacts configured through your preferred request management system. Users who encounter permission errors in the Google Cloud console have the option to copy an access request message and then send it using their preferred request management system.

These messages typically have the following format:

user@example.com is requesting a role on the resource example.com:example-project.

Requestor's message:

"I need access to example-project to complete my work."

You may be able to resolve this request by granting access directly at:

ACCESS_REQUEST_PANEL_URL

Or use the Policy Troubleshooter to determine what's preventing access for user@example.com:

POLICY_TROUBLESHOOTER_URL

You can address these requests in the following ways:

  • Resolve access directly: Access requests contain a link to an access request panel in the Google Cloud console. If the permission error is due to an allow policy, then you can resolve access directly from that panel.

    In the access request panel, you can review the request details and choose how you want to respond to the request. You can respond in the following ways:

    • Grant the requested role
    • Add the user to an existing group that already has the required access
    • Deny the request

  • View additional details in Policy Troubleshooter: Access requests also contain a link to Policy Troubleshooter, which lets you see which policies are blocking the user's access. You can use this information to decide how to resolve the user's access issue. For more information, see Identify policies causing permission errors on this page.

Manually resolve permission errors

If you are an administrator with permission to modify the access-related policies in your organization, then you can use these strategies to resolve permission errors, regardless of the policy type causing the error.

To resolve permission errors, you first need to determine which policies (allow, deny, or principal access boundary) are causing the error. Then, you can resolve the error.

Identify policies causing permission errors

To determine which policies are causing a permission error, use Policy Troubleshooter.

Policy Troubleshooter helps you understand whether a principal can access a resource. Given a principal, a resource, and a permission, Policy Troubleshooter examines the allow policies, deny policies, and principal access boundary (PAB) policies that impact the principal's access. Then, it tells you whether, based on those policies, the principal can use the specified permission to access the resource. It also lists the relevant policies and explains how they affect the principal's access.

To learn how to troubleshoot access and interpret Policy Troubleshooter results, see Troubleshoot IAM permissions.

Error messages in the Google Cloud console contain a link to a Policy Troubleshooter results page for the principal, permissions, and resource involved in the request. To view this link, click View troubleshooting details, then find the value in the Troubleshooting URL field.

Update access to resolve permission errors

After you know which policies are causing a permission error, you can take steps to resolve the error.

Often, resolving an error involves creating or updating allow, deny, or principal access boundary policies.

However, there are other options for resolving errors that don't involve updating policies. For example, you can add the user to a group that has the required permissions or add tags to exempt a resource from a policy.

To learn the different ways that you can resolve permission errors due to each of the different policy types, see the following:

Resolve allow policy permission errors

To resolve permission errors due to allow policies, do one of the following.

Grant a role with the required permissions

To find and grant a role with the required permissions, do the following:

  1. Identify an IAM role that contains the missing permissions.

    To see all of the roles that a given permission is included in, search for the permission in the IAM roles and permissions index, then click the permission name.

    If no predefined roles match your use case, then you can create a custom role instead.

  2. Identify a principal to grant the role to:

    • If the user is the only individual who needs the permission, then grant the role directly to the user.
    • If the user is part of a Google group containing users that all need similar permissions, then consider granting the role to the group instead. If you grant the role to the group, then all members of that group can use that permission, unless they have been explicitly denied from using it.

  3. Grant the role to the principal.

Approve a grant against a Privileged Access Manager entitlement

Privileged Access Manager entitlements let users request to be granted specific IAM roles. If you approve a user's request for a grant, then they're granted the requested roles temporarily.

If the user already have a Privileged Access Manager entitlement with a role that contains the required permissions, then they can request a grant against that entitlement. After they request the grant, you can approve the grant to resolve their permission error.

If a user doesn't have an entitlement, then you can create a new entitlement for them to request grants against.

Add the user to a Google group

If a Google group is granted a role on a resource, then all members of that group can use the permissions in that role to access the resource.

If an existing group has already been granted a role with the required permissions, then you can give a user the required permissions by adding them to that group:

  1. Identify a group that has a role with the required permissions. If you already used Policy Troubleshooter to troubleshoot the request, then you can review the Policy Troubleshooter results to identify a group with the required permissions.

    Alternatively, you can use Policy Analyzer to identify a group with the required permissions.

  2. Add the user to the group.

Resolve deny policy permission errors

To resolve permission errors related to deny policies, do one of the following.

Exempt yourself from a deny policy

If a deny rule is blocking a user's access to a resource, you can do one of the following to exempt the user from the rule:

  • Add the user as an exception principal in the deny rule. Exception principals are principals who are not affected by the deny rule, even if they're part of a group that's included in the deny rule.

    To add an exception principal to a deny rule, follow the steps to update the deny policy. When updating the deny policy, find the deny rule that blocks access, then add the user's principal identifier as an exception principal.

  • Add the user to a group that's exempt from the rule. If a group is listed as an exception principal, then all members of that group are exempt from the deny rule.

    To add the user to an exempt group, do the following:

    1. Use Policy Troubleshooter to identify the deny policies that are blocking access to the resource.
    2. View the deny policy.
    3. Check the list of exception principals for groups.
    4. If you identify an exempt group, add the user to the group.

Remove the permission from the deny policy

Deny rules prevent the listed principals from using specific permissions. If a deny rule is blocking a user's access to a resource, then you can remove the permissions that they need from the deny rule.

To remove permissions from a deny rule, follow the steps to update the deny policy. When updating the deny policy, find the deny rule that blocks access, then do one of the following:

  • If the deny policy lists the required permissions individually, then find the required permissions and remove them from the deny rule.
  • If the deny rule uses permission groups, then add the required permissions as exception permissions. Exception permissions are permissions that aren't blocked by the deny rule, even if they're part of a permission group that's included in the rule.

Exclude the resource from the deny policy

You can use conditions in deny policies to apply a deny rule based on a resource's tags. If the resource's tags don't meet the condition in the deny rule, then the deny rule doesn't apply.

If a deny rule is blocking access to a resource, then you can edit the conditions in the deny rule or the tags on the resource to ensure that the deny rule doesn't apply to the resource.

Resolve principal access boundary policy permission errors

By default, principals are eligible to access any Google Cloud resource. However, if they're subject to any principal access boundary policy, then they're only eligible to access the resources listed in the principal access boundary policies that they're subject to. In these cases, a principal access boundary policy might prevent a principal from accessing a resource.

To resolve errors related to principal access boundary policies, do one of the following.

Add the resource to a principal access boundary policy

If a resource is included in a principal access boundary policy that a user is subject to, then they're eligible to access that resource.

To add a resource to a principal access boundary policy, do one of the following:

Add a condition to exempt specific principals

You can use conditions in principal access boundary policy bindings to refine which principals the principal access boundary policy is enforced for.

If you don't want a user to be subject to principal access boundary policies, then use conditions in principal access boundary policy bindings to exempt the user from principal access boundary policies.

For this approach to resolve errors, you must exempt the user from every principal access boundary policy that they're subject to. Doing so will make the user eligible to access any Google Cloud resource.

We don't recommend this approach. Instead, consider adding the resource to a principal access boundary policy.

To view the principal access boundary policies that a user is subject to, list the policy bindings for the principal sets that they're included in. Each binding represents a principal access boundary policy that is bound to the principal set.

To learn how to add conditions to principal access boundary policy bindings, see Edit existing policy bindings for principal access boundary policies.

What's next