Gateway Troubleshooting & FAQ

If your release number when you go to <your-gateway>/ar-io/info is lower than the current release, you simply need to upgrade your gateway in order to reach the latest release.

If your release number includes the suffix "-pre" it means you are running your gateway from the development branch of the github repository, instead of the main branch. The development branch is used for staging work that the engineering team is in the middle of. Because of this, it can be much less stable than the main branch used for production and can cause significant issues.

Ensure that you are running the latest release, from the main branch, by running the below commands in your terminal:

sudo docker-compose down --rmi all

git checkout main

git pull

sudo docker-compose up -d

If this doesn't resolve the issue, you can also try a more extreme method of clearing out the incorrect docker images:

sudo docker-compose down

sudo docker system prune -a

sudo docker-compose up -d

Viewblock and ar://gateways use a very simple ping method for determining if a gateway is "up". There are plenty of reasons why this ping may fail while the gateway is running perfectly, so showing as down is not cause for concern. Just verify that your gateway is still running, and wait. Your gateway will show as up again soon.

This is normal. Your Observer is working to generate a report and that report will be displayed once it is complete.

This is not an issue with your observer. The short explanation is that your Observer is looking for tasks assigned to it by the AR.IO network contract, but there isnt anything there. You can safely ignore this error message.

When observing a gateway, there are two main pass/fail tests. "Ownership" and "ArNS Assessment"

• Ownership: This tests to see if the value set in your gateway AR_IO_WALLET value (in .env) matches the wallet used to join the AR.IO Network. If they don't match, update the value in your .env file and restart your gateway.

• ArNS Assessment: This tests to see if a gateway is able to resolve ArNS names correctly. The first thing you should check is if you have the ARNS_ROOT_HOST value set in your .env file. If not, set the value and restart your gateway. If this value is set, check to make sure you have current DNS records and SSL certificates for wildcard subdomains on your gateway.

Once you edit your .env file, you need to "rebuild" your gateway for the changes to take effect. As of release 3, every time you start your gateway with docker-compose it is automatically rebuilt. So all you need to do is shut your gateway down and restart it.

The most likely cause of this is inode exhaustion. Test this by running the command:

df -i

If one of the lines in the output says 100%, you have run out of inodes and so your filesystem is not capable of creating new files, even if you have available space. The solution is to delete files from your data folder in order to free up inodes.

This was a common issue prior to release #3, when Redis caching was introduced to reduce the number of small files created. If you are using an older version of the gateway, consider upgrading to mitigate the risk of inode exhaustion.

The first thing you should check if your gateway is not resolving ArNS names is that you have ARNS_ROOT_HOST set in your .env file. If not, set it to your domain name used for the gateway. For example, ARNS_ROOT_HOST=arweave.dev.

Once this value is set, restart your gateway for the changes to take effect.

If that doesn't resolve the issue, check your dns records. You need to have a wildcard subdomain ( *.< your-domain > ) set with your domain registrar so that ArNS names will actually point at your gateway. You can set this record, and generate an SSL certificate for it, in the same way you set the records for your primary domain.

This error message means that your SSL certificates have expired. You need to renew your certificates by running the same certbot command you used when you initially started your gateway:

sudo certbot certonly --manual --preferred-challenges dns --email <your-email-address> -d <your-domain>.com -d '*.<your-domain>.com'

Certbot SSL certificates expire after 90 days, and you will need to rerun this command to renew every time. If you provide an email address, you will receive an email letting you know when it is time to renew.

If you navigate to your domain and see a 404 error from Nginx (the reverse proxy server used in the setup guide) it means that your domain is correctly pointed at the machine running your gateway, but you have not properly configured your Nginx settings (or your gateway is not running).

The Set up Networking section of the setup guide has detailed instructions on configuring your Nginx server. If all else fails, try restarting Nginx, that usually clears any issues with the server clinging to old configurations.

sudo service nginx restart

A 502 error from Nginx means that Nginx is working correctly, but it is receiving an error from your gateway when it tries to forward traffic.

When using the manual certbot command provided in the setup guide:

sudo certbot certonly --manual --preferred-challenges dns --email <your-email-address> -d <your-domain>.com -d '*.<your-domain>.com'

You need to be sure that you are waiting after creating your TXT records for them to completely propagate. You can check propagation using a tool like dnschecker.org.

If you continue to have issues, you can check the official certbot instructions guide.

• Visit your gateway in a browser and see if your SSL certs are expired. This is the most common issue causing sudden stops in proper operation.

• Try restarting nginx, it sometimes has trouble looking at the new certs without a restart.

• Make sure ARNS_ROOT_HOST is properly set in your .env file. Updating this requires restarting your gateway.
• Make sure you have a DNS record set for *.<your-gateway-domain>. Since ArNS names are served as subdomains, you need to make sure all subdomains are pointed at your gateway.
• If your gateway is attempting to resolve the name, but times out, it's most likely a CU issue.

• AR.IO gateways are very robust, they can handle temporary errors gracefully and not affect normal operation. You should only be concerned if the error is consistent or it is causing your gateway to not function properly.

• Observers generate and submit their reports at specific times throughout the epoch. This is to ensure a healthy network throughout the entire epoch, not just at the start.
• Your observer wallet must match the observer wallet associated with your gateway in the AR.IO contract. You can check this by navigating to your gateway in ar://gateways.

• This happens when a request to a CU fails, and your gateway receives an html failure message instead of the expected JSON response. This will normally clear up on its own after congestion on that CU dies down, but if it is persistent try switching to a different CU.

• This is normal. It means you have reached the current Arweave block and need to wait for more before you can index them.

• This is normal. If a gateway fails to resolve an arns name within 3 seconds, it will fall back to a trusted gateway (arweave.net by default) to help resolve the name.

• There are many reasons a gateway could fail an epoch. Following these steps is usually enough to identify and correct the issue:
  • Try to visit your gateway in a browser and see if your SSL certs are bad
  • Try to resolve an ArNS name on your gateway. If it fails to resolve, check the console and your gateway logs for errors
  • Look at the observation reports that failed your gateway, they will list the reason for failure

• Gateway protocol rewards are calculated as 0.1% of the protocol balance (0.05% after August 2025) split between all gateways in the network. A change in the protocol balance or the number of gateways in the network between epochs will result in the reward for an individual gateway changing.

• The Observer rewards are separate from protocol rewards, and if your gateway is selected as an observer for an epoch, assuming it performs its duties well, it will receive additional rewards

The observer selection process uses a weighted random selection method that considers multiple factors beyond just stake:

• Stake Weight (SW): Ratio of your total staked ARIO tokens (including delegated stake) to the network minimum
• Tenure Weight (TW): How long your gateway has been part of the network (capped at 4 after 2 years)
• Gateway Performance Ratio Weight (GPRW): Ratio of epochs where you correctly resolved names vs total participation
• Observer Performance Ratio Weight (OPRW): Ratio of epochs where you successfully submitted reports vs total observer periods

A composite weight (CW) is calculated as: CW = SW × TW × GPRW × OPRW

Up to 50 gateways are chosen as observers per epoch. If there are more than 50 gateways, selection is randomized based on these normalized weights. Even with a high stake, other factors like performance and tenure affect your chances of being selected.

• There is a 90 day locking period when withdrawing stake, either from delegated stake or operator stake on your gateway. This locking period can be skipped, for a fee. The fee starts at 50% of the withdrawal amount, and goes down over time. If you selected instant withdrawal, you paid the fee to skip the locking period.

• The minimum operator stake for gateways (10,000 ARIO) cannot be instantly withdrawn, it is subject to the full 90 day locking period, and withdrawal can only be started by removing your gateway from the network.

• If possible, leave your original server running while you prepare the new one
• Set up the new server following the same steps you used to set up the original server
  • This includes setting up SSL certificates for the new server
• You must use the same gateway wallet when setting up the new server
• The observer wallet may be changed at any point, but requires extra steps. It is recommended you use the original observer wallet as well
• Once the new server is set up, change your DNS A records to point at the new server
• After your DNS records are set and you have verified your gateway is operating correctly, shut down the original server
• No changes need to be made in the network contract or on ar://gateways

• Yes
• Configure your new domain to point at your gateway, including setting up SSL certificates
• Update your NGINX (or other reverse proxy) server to recognize the new domain. This usually requires a restart of NGINX
• Update the ARNS_ROOT_HOST variable in your .env and restart the gateway
• Using ar://gateways, update your gateway settings to change the FQDN in the contract
• Your gateway is now using the new domain name for normal operation.