Troubleshoot OS package issues

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

For information on resolving issues with Artifact Registry remote repositories for OS packages, see Troubleshoot remote repositories.

Authentication and permissions issues

You cannot connect to a repository for actions such as installing a package. The output from the package manager includes a 401 or 403 error, which indicates issues with authentication or permissions.

Example Apt errors:

Err:1 ar+https://us-central1-apt.pkg.dev/projects/my-project my-package Release
  Error downloading: code 401

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:

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.
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.
Verify that you have followed the steps to prepare the VM to access the repository. See the Apt or Yum preparation instructions.
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 that doesn't include the Apt repository signing key.

To resolve this issue, do the following:

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.
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
```

Missing recently uploaded artifacts

If your Apt or Yum client does not find a package that was recently uploaded or imported to your repository, it might be because the process to regenerate the Apt or Yum package index is not yet complete.

For small repositories, regenerating the Apt or Yum index file can take several seconds. For larger repositories, reindexing might take several minutes or longer.

To verify that a package was successfully added to the repository, use the Google Cloud CLI to list files in the package. Run the command:

gcloud artifacts files list \
    --package=PACKAGE \
    --project=PROJECT-ID \
    --repository=REPOSITORY \
    --location=LOCATION

For example, you can check that the python-gflags package named python3-gflags_1.5.1-5_all.deb was uploaded successfully to the repository us-central1-apt.pkg.dev\apt-project\apt-repo with the command:

gcloud artifacts files list \
    --package=python-gflags \
    --project=apt-project \
    --repository=apt-repo \
    --location=us-central1

If the package was uploaded successfully, the file appears in the output with a unique identifier in the file name, similar to the following example:

FILE                                                                  CREATE_TIME          UPDATE_TIME          SIZE (MB)  OWNER
pool/python3-gflags_1.5.1-5_all_2414c7af6a64c99a5f488aad366d637a.deb  2023-01-12T20:39:53  2023-01-12T20:39:53  0.035      projects/apt-project/locations/us-central1/repositories/apt-repo/packages/python3-gflags/versions/1.5.1-5

Authentication error for some uploaded or imported packages

If the time to import or upload files exceeds the authentication token expiry period, uploads beyond the expiry period will fail. Tokens expire 60 minutes after you obtain them. An error similar to the following example appears in output from the import command if the token has expired.

errors:
- error:
    code: 16
    message: The request does not have valid authentication credentials.
  gcsSource:
    uris:
    - gs://my-bucket/debs/python/python3-gflags_1.5.1-5_all.deb

To address this issue:

Try uploading or importing the specific package only to verify that you can add the package individually instead of in a batch import.
If multiple packages failed, import or upload in smaller batches so that the operation does not exceed the token expiry period.

Troubleshoot OS package issues

Authentication and permissions issues

Compute Engine VM

Other VM