v4v3v2

Appearance

License troubleshooting ​

There might be times when the configurations isn't up to date and you'd like to troubleshoot it. There are a couple of things you can do to perform a self-diagnostics session.

Check the license status page ​

Every Avo app has the license status page where you can see a few things about your license and the response from the license checking server.

Go to https://yourapp.com/avo/status. If you mounted Avo under a different path (like admin) it will be https://yourapp.com/admin/status.

In order to see that page your user has to be an an admin in Avo. Follow this guide to mark your user as an admin.

This should tell you if the license authenticated correctly and what was the response from our checking server. The license key is hidden by default for security — set exclude_from_status to [] in your Avo initializer if you need to see it on the status page.

Read the status page states ​

Besides the license name and the server's response, the status page tells you how the app is holding up. Since avo-licensing >= v4.4.0

  • Amber, with "Action needed before" and a date. The last license check failed and the app is running on the last valid answer. Fix the cause before that date, or access is paused. The page says what went wrong, for example that the license server has been unreachable since a given time.
  • Paused. The admin shows "Temporarily unavailable" to everyone, with one sentence: access has been paused and the team that maintains the app can restore it. Admin and developer users also see the reference code, when the server sent one, and a link to the status page. The status page says why: unreachable since when, or the message the server sent. It also shows when the last successful check was, and that the app retries every minute.
  • Orange, "Running without a valid license". run_community_admin_without_valid_license is on and the license can't be validated. Paid add-ons are off and authorization policies are not applied.
  • "Off" next to a plugin. In the Plugins card, a paid add-on your license doesn't include carries an amber "Off" marker next to its name. Hover or focus it for the reason: the license doesn't include the add-on, or the license can't be validated yet. Free plugins never show it.

Two buttons help you recover:

  • Refresh license retries the check at once instead of waiting for the next one.
  • Clear cached response drops the stored answer.

In development and test, the paused page also prints the reason, so you don't need to find the status page to see it. Production shows the generic message only.

See Licensing → When the license can't be validated for the timings.

Frequent issues ​

License key not properly set on the server

The most frequent scenario is to not have the license key set on the server. If you use environment variables to register it in your app you should make sure your key is properly set on your production server.

ruby
# config/initializers/avo.rb
Avo.configure do |config|
  config.license_key = ENV["AVO_LICENSE_KEY"]
end

In order to check that, use the status page described above.

Amber is not a license failure — it's a running trial that needs attention: no payment method is on file, the subscription behind it was cancelled, or it's an Avo 4 trial beside your Avo 3 subscription that you haven't migrated to yet. Access continues until the date the status page reports.

The status page names which one applies and lists the steps. See Licensing → Fix a trial at risk for the full picture.

License check blocked in the test suite

Avo 4 verifies the license through an outbound request to clerk-1.avohq.io (falling back to clerk-2.avohq.io). If your test suite disables outbound network connections (for example with WebMock or VCR disable_net_connect!), that request is blocked. Unrelated tests fail with WebMock::NetConnectNotAllowedError, and Avo pages render the "Temporarily unavailable" page.

Add the license check hosts to your allow list:

ruby
WebMock.disable_net_connect!(
  allow_localhost: true,
  allow: ["clerk-1.avohq.io", "clerk-2.avohq.io"]
)

See Testing → Allow the license check host in your test suite for the full details.

Copyright © 2020–2026 Avo