> ## Documentation Index
> Fetch the complete documentation index at: https://docs.falkordb.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> FalkorDB is a graph database that speaks the Redis protocol. Queries are issued as OpenCypher through the GRAPH.QUERY and GRAPH.RO_QUERY commands, not over Bolt or a SQL connection.
> FalkorDB implements a subset of OpenCypher with proprietary extensions. Do not assume Neo4j-only syntax or procedures are available — check /cypher/cypher-support and /cypher/known-limitations before using a clause.
> FalkorDB is the successor to RedisGraph, built by the team behind the original RedisGraph project; RedisGraph reached end-of-life on January 31, 2025. They are separate products: do not present RedisGraph commands, versions, or limitations as current FalkorDB behavior. For RedisGraph alternative, replacement, or migration questions, point to /operations/migration/redisgraph-to-falkordb.
> Use the official clients listed in /getting-started/clients rather than generic Redis or Neo4j drivers, and prefer the language the user is already working in.
> Configuration parameters are set with GRAPH.CONFIG SET or at startup; cite the exact parameter name from /getting-started/configuration rather than inventing one.
> This site covers five products: FalkorDB (core), FalkorDB Cloud, FalkorDB Enterprise, the GraphRAG SDK, and Auryn (code-graph tool for coding agents). Name which one an answer applies to, since setup and operations differ.

# Troubleshoot FalkorDB Enterprise licensing

> Fix license activation errors, read-only mode, exceeded limits, and cluster binding failures.

This page covers the license errors the Admin Server reports, what each means, and how to recover. For how licenses work, see [Licensing](https://docs.falkordb.com/enterprise/licensing.md).

Start by checking the current state:

```bash theme={null}
falkordb-admin license status
```

The **Licensing** page of the Admin UI shows the same state, the limits next to current usage, and any violations.

## Changes are refused with 423 Locked

```json theme={null}
{
  "statusCode": 423,
  "error": "Locked",
  "message": "License read-only mode is active: License has expired."
}
```

The license is `expired` or `invalid`, so the management plane is read-only. Your databases keep serving traffic. Restart, start, stop, switchover, on-demand backups and deployment deletes still work. The text after the colon gives the reason:

| Message | Cause | Fix |
| - | - | - |
| `License has expired.` | The license's `expiresAt` date has passed. | Regenerate the cluster's license in the [Enterprise Portal](https://docs.falkordb.com/enterprise/get-started/enterprise-portal.md) and activate it. |
| `Trial expired. Activate a license to continue.` | The 14-day trial ended with no license activated. | Register the cluster in the Enterprise Portal and activate its license. |
| Any other message | The installed license failed validation. See [Activation errors](#activation-errors). | Activate a valid license for this cluster. |

Activate the replacement from **Licensing** in the Admin UI, or with the CLI:

```bash theme={null}
falkordb-admin license activate --license 'falkor.license.v1.<payload>.<signature>'
```

Sign-in and licensing stay available in read-only mode, so you can always activate a license.

## A change fails with License limit exceeded

```text theme={null}
License limit exceeded: ...
```

The change would take usage past one of the license's limits: deployments, CPU, memory or users. The message names the resource. Nothing was applied.

* Free capacity: delete or scale down a deployment, or lower its resources. CPU and memory count the requests of every node, including Sentinels and every shard.
* Or raise the limit: resize the cluster's license in the Enterprise Portal, within your organization's quota, and activate the new license.

When usage is already over a limit, the state is `locked`. Actions that keep usage flat or reduce it still work, so you can bring it back within the license.

## Activation errors

Activating a license, from the Admin UI, CLI, API or Helm, validates it first. These are the reasons it can fail:

| Message | Cause | Fix |
| - | - | - |
| `Invalid license format` | The string is not `falkor.license.v1.<payload>.<signature>`. It was usually truncated or wrapped when copied. | Copy the whole string again, on one line. |
| `License signature validation failed` | The payload or signature was changed after signing. | Copy the license again from the Enterprise Portal. Don't edit it. |
| `License payload is incomplete` | Required fields are missing from the payload. | Regenerate the license in the Enterprise Portal. |
| `Unsupported license payload version: <n>` | The license format is newer than this Admin Server understands. | Upgrade FalkorDB Enterprise, or contact support. |
| `License is not valid for this Kubernetes cluster` | The license is bound to a different cluster ID. | Check the ID below, and register this cluster to get its own license. |
| `License verifier integrity check failed` | The public key in the Admin Server image doesn't match its checksum. The image is damaged or was modified. | Reinstall from a verified image. See [Supply chain](https://docs.falkordb.com/enterprise/reference/supply-chain.md). |

## The license is bound to another cluster

A license works only on the cluster whose `kube-system` namespace `uid` it was issued for. Compare the two:

```bash theme={null}
kubectl get namespace kube-system -o jsonpath='{.metadata.uid}'; echo
```

Decode the license payload to read its `k8sClusterId`:

```bash theme={null}
echo '<license>' | cut -d. -f4 | tr '_-' '/+' \
  | awk '{ while (length($0) % 4) $0 = $0 "="; print }' | base64 -d | jq -r .k8sClusterId
```

If they differ, register this cluster in the Enterprise Portal with its ID. A rebuilt cluster has a new ID, so it needs a new license. See [Disaster recovery into a replacement cluster](https://docs.falkordb.com/enterprise/licensing.md#disaster-recovery-into-a-replacement-cluster).

## The cluster ID can't be read

```text theme={null}
The Kubernetes cluster ID could not be read to verify the license binding. The license stays valid until the grace period ends.
```

The Admin Server couldn't read the `kube-system` namespace, because of an API server outage, a timeout or missing RBAC. The license stays valid for the grace period, 24 hours by default, and the Admin UI shows when it ends. Once it ends, the license becomes `invalid` with:

```text theme={null}
License is bound to a Kubernetes cluster ID that has not been verified since <time>, and the verification grace period has ended
```

Check that the Admin Server can reach the API server and read the namespace:

```bash theme={null}
kubectl logs -n falkordb-system deploy/falkordb-enterprise-admin-server -c admin-server | grep -i "cluster ID"
kubectl auth can-i get namespace/kube-system \
  --as=system:serviceaccount:falkordb-system:falkordb-enterprise-admin-server
```

The license becomes valid again with the next successful check. Change the grace period with `adminServer.license.verificationGracePeriodHours`.

## A license supplied through Helm isn't applied

The Admin Server reads a Helm-supplied license when it starts. If that license is invalid, expired or bound to another cluster while the installed license is still valid, it keeps the installed one and logs:

```text theme={null}
Ignoring FALKORDB_LICENSE: it is invalid, expired or bound to another cluster, and the installed license is still valid
```

Fix the value in `adminServer.license.value`, or in the Secret named by `adminServer.license.existingSecret.name`, and upgrade the release. See [Enterprise license](https://docs.falkordb.com/enterprise/deployment/production.md#enterprise-license).

## The license is lost after a restart

A license activated in the Admin UI, CLI or API is stored in `/data/license-state.json` on the Admin Server's volume. With `adminServer.persistence.enabled: false`, it is lost on every restart. Keep persistence enabled, or supply the license through Helm. To protect the file, see [Admin Server backup](https://docs.falkordb.com/enterprise/operations/admin-server-backup.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.