Articles

Manage Aqua Security Licenses (2026)

April 16, 2026 4 min read

Aqua Security licenses are managed through a central configuration file, and issues arise when this file is malformed, outdated, or missing required fields, preventing the Aqua platform from authenticating its components and enforcing security policies.

Here’s how to troubleshoot and manage Aqua Security licenses:

Common Causes and Fixes

1. Expired License:

  • Diagnosis: Check the expirationDate field within your Aqua license file. You can do this by opening the license file (typically licenses.json or similar) in a text editor.
  • Fix: Obtain a new license file from Aqua Security and replace the existing licenses.json file on your Aqua Server.
  • Why it works: The Aqua Server periodically checks the expiration date. Once expired, it stops issuing new tokens for components, effectively disabling the platform. A new license reactivates the system.

2. Incorrect License Format/Syntax Errors:

  • Diagnosis: Inspect the licenses.json file for any JSON syntax errors (e.g., missing commas, unbalanced brackets, incorrect quoting). Use a JSON linter (like jq . licenses.json or an online JSON validator) to verify its structure.
  • Fix: Correct any identified syntax errors in the licenses.json file. Ensure all keys and string values are properly quoted, and that commas separate elements in arrays and key-value pairs in objects.
  • Why it works: The Aqua Server parses this JSON file to load license details. Malformed JSON prevents successful parsing, leading to license loading failures.

3. Missing Required Fields:

  • Diagnosis: Verify that the license file contains essential fields such as licenseId, issueDate, expirationDate, licenseType, and customerName. Compare your file against a known good license structure or Aqua’s documentation.
  • Fix: Ensure all mandatory fields are present and populated with valid data. If fields are missing, contact Aqua Support to get a corrected license file.
  • Why it works: These fields are critical for the Aqua Server to identify the customer, the license’s validity period, and its capabilities. Their absence can lead to an unidentifiable or invalid license.

4. Incorrect License Type or Feature Flags:

  • Diagnosis: Check the licenseType field and any associated feature flags within the licenses.json. Ensure they align with the features you intend to use and the license tier you’ve purchased. For example, a platform license type is required for core Aqua Server functionality.
  • Fix: If the licenseType or feature flags are incorrect, you’ll need a new license file from Aqua Security that accurately reflects your subscription.
  • Why it works: The licenseType and feature flags dictate which modules and functionalities are enabled within the Aqua platform. An incorrect setting can disable features or prevent the server from starting.

5. License File Location or Permissions:

  • Diagnosis: Confirm that the licenses.json file is located in the correct directory for your Aqua Server deployment. For standard installations, this is typically /etc/aquasec/licenses.json. Also, check file permissions to ensure the Aqua Server process has read access. The ls -l /etc/aquasec/licenses.json command will show permissions.
  • Fix: Move the licenses.json file to the correct directory and ensure it’s readable by the user running the Aqua Server process (often root or a dedicated aqua user). Use chmod 644 /etc/aquasec/licenses.json and chown <aqua_user>:<aqua_group> /etc/aquasec/licenses.json if necessary.
  • Why it works: The Aqua Server process needs to be able to locate and read the license file at startup. Incorrect location or insufficient permissions will prevent it from accessing the license information.

6. Corrupted License File (Beyond Syntax):

  • Diagnosis: Even if syntactically correct, the file might be corrupted due to incomplete downloads or disk errors. Try re-downloading the license file or copying it again.
  • Fix: Obtain a fresh copy of the licenses.json file from Aqua Security and replace the existing one.
  • Why it works: A physically corrupted file, even with valid JSON structure, can lead to read errors at the operating system level, preventing the Aqua Server from processing it.

7. Multiple License Files:

  • Diagnosis: Ensure there is only one licenses.json file in the Aqua license directory. Having multiple files can confuse the Aqua Server.
  • Fix: Remove any duplicate or old licenses.json files, leaving only the currently active and valid license file.
  • Why it works: The Aqua Server is designed to load a single, primary license file. Multiple files can lead to unpredictable behavior or the incorrect license being loaded.

After applying any fixes, restart the Aqua Server service for the changes to take effect. The next error you’ll likely encounter if all license issues are resolved is a problem with component communication, such as the Aqua Gateway failing to connect to the Aqua Server.

Want structured learning?

Take the full Aqua course →