Troubleshoot OS package issues

Stay organized with collections Save and categorize content based on your preferences.

Learn about troubleshooting steps that you might find helpful if you run into problems managing OS packages in Artifact Registry.

Authentication and permissions issues

You receive 403 error message when you try to connect to the repository from a virtual machine (VM) instances:

Example Apt error:

E: Failed to fetch https://us-central1-apt.pkg.dev/projects/my-project/dists/quickstart-apt-repo/main/binary-amd64/Packages  403  Forbidden [IP: 74.125.20.82 443]
E: Some index files failed to download. They have been ignored, or old ones used instead.

Example Yum error:

/repodata/repomd.xml: [Errno 14] HTTPS Error 403 - Forbidden

There are a number of possible causes for these errors. Ensure that your VM meets the following requirements:

  1. Verify that the VM has an associated service account.

    Compute Engine VM

    1. Go to the VM instances page.
    2. In the list of VMs, click the name of your VM.

      On the Details tab, the service account and access scopes appear under API and identity management.

    By default, Compute Engine VMs use the Compute Engine default service account and have a limited set of access scopes. The default service account email address is in the format PROJECT_NUMBER-compute@developer.gserviceaccount.com.

    To change the service account or attach a service account to a VM, see the Changing the service account and access scopes for an instance.

    Other VM

    For other VMs, you must have a service account to act on behalf of the VM.

    1. Create a service account if you do not have one.

    2. Grant the Artifact Registry Reader (roles.artifactregistry.reader) role while you're creating the service account so that you do not need to configure permissions in a separate step.

  2. Ensure that the VM service account has read permissions to the repository as well as the cloud-platform API access scope.

    Compute Engine VM

    Artifact Registry automatically retrieves VM service account credentials. The required configuration depends on whether you are using the default service account or a user-managed service account.

    Default service account

    If the VM uses the default service account, this service account has the Editor role by default, which includes read permissions to repositories in the same project. If the repository is in a different project than the VM, grant the Artifact Registry Reader role to the VM service account.

    Additionally, the default service account does not have all required API access scopes.

    To set the cloud-platform access scope,

    1. Stop the VM instance, replacing INSTANCE with the VM instance name.

      gcloud compute instances stop INSTANCE
      
    2. Set the access scope:

      gcloud compute instances set-service-account INSTANCE \
          --scopes=cloud-platform
      
    3. Restart the VM instance.

      gcloud compute instances start INSTANCE
      
    User-managed service account
    If the VM uses a user-managed service account, grant the Artifact Registry Reader role to the VM service account. User-managed service accounts have the cloud-platform access scope.

    Other VM

    Grant the Artifact Registry Reader role to the VM service account. By default user-managed service accounts have the cloud-platform access scope.

  3. Verify that you have followed the steps to prepare the VM to access the repository. See the Apt or Yum preparation instructions.

  4. Verify that you have correctly configured Apt or Yum to access the repository.

    If you are connecting to an Apt repository from a Compute Engine VM, make sure that the repository URL includes the ar+ prefix.

Credential helper issues

The following error message appears when the VM can't locate the Apt credential helper:

E: Unable to locate package apt-transport-artifact-registry

The error occurs when you try to install the apt-transport-artifact-registry package on a VM that was created from an image doesn't include the Apt repository signing key.

To resolve this issue, do the following:

  1. Install the signing key on the VM:

    Debian VM

    Install the Apt repository signing keys, using the following command:

    curl https://LOCATION-apt.pkg.dev/doc/repo-signing-key.gpg | sudo apt-key add -
    

    Replace LOCATION with the location of the repository.

    Ubuntu VM

    Install the Apt repository signing keys, using the following command:

    curl https://LOCATION-apt.pkg.dev/doc/repo-signing-key.gpg | sudo apt-key add - && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
    

    Replace LOCATION with the location of the repository.

  2. Re-try the VM preparation steps.

Authentication plugin issues

The following error message appears when there is an issue with the Yum or DNF authentication plugin:

Plugin "artifact-registry" can't be imported

This error can occur for several reasons. To resolve the error, try running the plugin directly to confirm dependencies, check for Python issues, or reveal other possible underlying problems.

To run the plugin directly, use one the of following commands:

  • For the Yum plugin:

    python /usr/lib/yum-plugins/artifact-registry.py
    
  • For the DNF plugin:

    python3 /usr/lib/pythonVERSION-NUMBER/site-packages/dnf-plugins/artifact-registry.py
    

    Replace VERSION-NUMBER with the default Python version for the Linux distribution. For example, Enterprise Linux 8 includes Python 3.6.

    You can list the files in the installed plugin package to verify name of the Python library directory.

    rpm -ql dnf-plugin-artifact-registry|grep artifact-registry.py