Troubleshoot issues with the Metadata service

Metadata API

Token Expired

When you encounter a “401 - Unauthorized" error code while interacting with the Metadata service, it often indicates an issue with your token. Common token-related issues include:

Invalid or missing token

To address this issue:

  • Ensure token presence: Verify that your request includes a valid token in the required header.
  • Check token validity: Ensure the token hasn't expired.
  • Avoid token reuse: If you're using a token from a different instance, it will be rejected. Each instance has its own unique token.

Token expiration

To address this issue:

  • Set an appropriate TTL: When creating a token, specify a suitable time to live (TTL) to prevent premature expiration.
  • Monitor the TTL: Regularly check the token's remaining TTL to avoid unexpected expiration.
  • Renew the token: For long-running processes, periodically renew the token to extend its validity.

Incorrect usage

To address this issue:

  • Check the header: Ensure that the token is included in the correct (Metadata-Token) HTTP header.

cloud-init

View cloud-init logs

If you encounter issues with cloud-init or your user data, you can review the logs and output logs by running one of the commands below:

cat /var/log/cloud-init.log
cat /var/log/cloud-init-output.log

If you are not able to access your system through SSH, you can use Lish or boot your Linode into rescue mode and mount your disks.

Run the cloud-init command

The cloud-init command-line tool can be used to gather more information or perform certain actions. Here are some commands you can use to help troubleshoot cloud-init.

  • cloud-init status --long: This provides information about the status of cloud-init. You will notice different output depending on if it is actively running or if it has run in the past. See cloud-init status.
  • cloud-init query v1 and cloud-init query userdata: This outputs either the instance data or the user data provided by the Metadata service. Other metadata is also exposed by entering a different query key. See cloud-init query.