Licensing
This page describes how a Foundation4 license is bound to an installation, how operators read the system ID, apply and renew a license, and what the license limits. The page also describes how Foundation4 behaves when the license is invalid, expired or exceeded. Operators and administrators who install or run Foundation4 use this page.
The commands on this page read the production values file foundation4ai.values.yaml, created in Install on Kubernetes. An evaluation installation uses evaluation.values.yaml instead.
License binding
Every Foundation4 installation requires a license, including an evaluation installation. The Foundation4 provider issues each license for one system ID. The system ID identifies one database schema on one PostgreSQL cluster.
For licenses of version 3, the current license version, Foundation4 computes the system ID from the PostgreSQL system identifier, the database name and the schema in database.schema. PostgreSQL assigns the system identifier when a database cluster is created with initdb, and physical copies of the cluster keep the identifier. The system ID is a string of 64 hexadecimal characters and does not depend on the Foundation4 tables, so the system ID exists before the database migration.
Foundation4 reads the system identifier with the PostgreSQL function pg_control_system(). Stock PostgreSQL lets every database user run the function; a managed database service that revokes this permission grants the permission to the Foundation4 user, as Database describes. Without the permission, the system ID cannot be computed.
Licenses of versions 1 and 2 keep the earlier system ID, computed from PostgreSQL catalog object identifiers (OIDs) of the schema in database.schema, the owner of that schema and the api_keys table.
| Event | System ID of version 3 | License |
|---|---|---|
| Pod restart, Helm upgrade, Foundation4 upgrade, application release reinstalled against the same database | Unchanged | Remains valid |
| PostgreSQL restart or minor version upgrade | Unchanged | Remains valid |
Failover to a physical replica, physical restore with pg_basebackup, storage snapshot of the cluster | Unchanged, because the copy keeps the system identifier | Remains valid |
| Bundled PostgreSQL pod deleted or rescheduled (evaluation profile) | Unchanged, because the volume claim keeps the database | Remains valid |
Logical restore with pg_dump and pg_restore into a database of the same name on the same cluster | Unchanged; new for licenses of versions 1 and 2 | Remains valid for version 3 |
| New database, including a new installation | New | New license required |
| Logical restore into another cluster or under another database name | New | New license required |
| Major PostgreSQL version upgrade, which creates a new cluster | New | New license required |
| Move to a new managed database instance | New | New license required |
Database or database.schema renamed | New | New license required |
| Volume claim of the bundled PostgreSQL deleted (evaluation profile) | New, because the database is recreated empty | New license required |
Schema assigned to a new owner, or api_keys table recreated | Unchanged; new for licenses of versions 1 and 2 | Remains valid for version 3 |
The following rules keep the system ID stable:
- Database and schema names. The database name and
database.schemado not change after the license is installed. The installation Jobs, the command-line tools, the API server and the workers compute the system ID from the samedatabase.schema. - Schema ownership. For licenses of versions 1 and 2, the owner of the schema does not change after the license is installed.
- Planned changes. Before a change that creates a new system ID, such as a major PostgreSQL version upgrade, the operator requests a license for the new system ID, so that the license is ready at the switch-over.
Database describes the database requirements, and Backup, restore and upgrades describes restores and major PostgreSQL version upgrades.
System ID retrieval
The system ID is available from three sources:
- License check Job log. The Job
foundation4ai-api-server-license-checkprints the system ID in the first line of the log, at every installation and upgrade of the application release. Helm deletes the Job after a successful check, so the log remains after a failed check, until the next install or upgrade. This source is the only one available during the first installation. - Command in a running pod.
foundation4ai license system-idprints the system ID of the database and schema that the pod is configured for. - Startup warning. When the license does not match, the API server and the workers log a warning with the system ID before exiting.
Read the system ID from the log of a failed license check Job:
kubectl logs -n foundation4ai job/foundation4ai-api-server-license-check
Expected result: the first line holds the system ID, the second line holds the license status, and the last line repeats the status as an error.
SystemID: <system ID>
Checking for a valid license... Invalid
Error: "License check failed: Invalid"
When the database user cannot run pg_control_system(), the first line reads SystemID: unavailable (<reason>).
Read the system ID from a running API server pod:
kubectl exec -n foundation4ai deploy/foundation4ai-api-server -c server -- \
./foundation4ai license system-id
Expected result: one line with 64 hexadecimal characters. A database user without access to pg_control_system() produces Error: "Failed generating system id: the database user cannot read pg_control_system()" instead.
Find the startup warning in the log of an API server that exited:
kubectl logs -n foundation4ai deploy/foundation4ai-api-server -c server --previous | \
grep "Failed to validate license for system id"
Expected result: a WARN line that ends with Failed to validate license for system id: <system ID>.
License contents
foundation4ai license details prints the contents of a license after checking the license against the system ID of the database:
kubectl exec -n foundation4ai deploy/foundation4ai-api-server -c server -- \
./foundation4ai license details '<license>'
Expected result for a license that matches the database, with each value in angle brackets replaced by the license contents:
License: <license holder> (expires on <date> <time> UTC)
System ID: <system ID>
Version: <license version>
Limits:
Pipelines: <limit>
Documents: <limit>
The output has the following parts:
- Holder and expiry. The first line names the license holder and the expiry date and time in UTC, or
(perpetual)for a license without an expiry date. - Optional lines.
Description:andEnvironment:lines appear when the license carries these fields. - Version. The license version. Licenses bound to the PostgreSQL system identifier have version 3.
- Limits. One line for each limited object type:
Pipelines,Documents,Fragments,Text Splitters,Embedding Models,Agents,LLMs,Api KeysandTaxonomies. An object type without a line, or with the limit0, has no limit, andnonemeans that no object type is limited. - Errors. When the license cannot be used, the command prints
Error: "<result>"instead of the details and exits with status 1. The result isInvalidfor a license that is malformed, of an unsupported version or issued for another system ID,Expired,Missingfor an empty value, orThe system id for this license version could not be computed.
Command-line interface describes the license subcommands.
License installation
The first installation obtains the system ID, then installs the license. The steps are part of Install on Kubernetes and of steps 4 to 6 of Install for evaluation:
- The secrets file holds a placeholder, such as
pending, or an empty value inFOUNDATION4AI_APP_LICENSE. - The first application install migrates the database, then stops at the license check, which prints the system ID and fails.
- The operator sends the system ID to the Foundation4 provider and receives the license.
- The operator sets the license in
foundation4ai.secrets.env, applies the Secret and runs the application install again.
The license check Job fails at once after a failed check, so Helm reports a failed pre-install hook without waiting for the Helm timeout. The failed Job and the log remain until the next install or upgrade of the application release, which replaces the Job.
License renewal
A renewed license replaces the license of a running installation, for example before the expiry date or when the limits change. The renewed license is checked first, because a license that fails the check stops the upgrade and every restarted pod.
-
Check the renewed license against the database:
kubectl exec -n foundation4ai deploy/foundation4ai-api-server -c server -- \./foundation4ai license details '<renewed license>'Expected result: the license details, starting with
License:, and the expected expiry date and limits.Error: "Invalid"orError: "Expired"means that the license cannot be used; the procedure stops here. -
Replace the value of
FOUNDATION4AI_APP_LICENSEinfoundation4ai.secrets.envand apply the Secret:kubectl kustomize . | kubectl apply -n foundation4ai -f -Expected result:
secret/foundation4ai-secrets configured. -
Upgrade the application release, which runs the license check and restarts the API server and the workers with the renewed license, then check the license that the API server reads:
helm upgrade foundation4ai ./charts/foundation4ai \-n foundation4ai -f foundation4ai.values.yaml --wait --timeout 10mkubectl exec -n foundation4ai deploy/foundation4ai-api-server -c server -- \./foundation4ai license checkExpected result: Helm reports
STATUS: deployed, and the check printsChecking for a valid license... OK.
When the application release is rendered without access to the cluster, the API server and the workers are restarted by hand after step 3, as Secrets and keys describes.
Foundation4 reports no warning before a license expires. The operator records the expiry date of each license and renews the license before that date. GET /license, with an admin API key such as the master key, returns the expiry date, the limit of each object type and the number of objects in use:
curl -s "$FOUNDATION4_URL/license" \
-H "x-api-key: $FOUNDATION4_API_KEY" \
-H "x-api-key-secret: $FOUNDATION4_API_SECRET"
Expected result: HTTP 200 with the license details. The following response is shortened to two of the nine entries of items:
{
"name": "Example Organization",
"description": null,
"environment": "production",
"version": 3,
"created": "2026-11-01T00:00:00+00:00",
"expires": "2027-11-01T00:00:00+00:00",
"valid": true,
"status": null,
"items": [
{"object_type": "pipelines", "limit": 10, "used": 4, "estimated": false},
{"object_type": "documents", "limit": 1000000, "used": 182340, "estimated": true}
]
}
expires is null for a perpetual license, and limit is null for an object type without a limit. valid and status report the license as the API server enforces the license. GET /license describes every field.
License enforcement at startup
The API server and each worker read the license at startup. The license check Job checks the license at every installation and upgrade of the application release. The database migration Job and the master key Job do not read the license. A license that is missing, malformed, issued for another system ID, of an unsupported version or expired stops the process:
| Process | Output |
|---|---|
| License check Job | SystemID: <system ID>, then Checking for a valid license... followed by Missing, Invalid, Expired or The system id for this license version could not be computed, then Error: "License check failed: <result>". The Job fails, and the install or upgrade stops. |
| API server | Error: "Failed to initialize server: License check failed: Invalid license" |
| Worker | Error: "License check failed: Invalid license" |
An expired license replaces Invalid license with Expired license, and a system ID that cannot be computed with Error computing system id. The API server and the workers also log the warning Failed to validate license for system id: <system ID>.
A license expiry does not stop a running API server. The workers stop after the expiry, as License enforcement at runtime describes. A pod that restarts after the expiry, after a node failure or during a rolling update, does not start again until a valid license is installed.
HTTP 401 on POST /login is a credential error, never a license error. A license error appears either at startup or as HTTP 403.
License enforcement at runtime
The API server checks the license before every operation that creates or changes data:
- Checked operations. Creating and updating pipelines, text splitters, embedding models, agents, LLMs, API keys and taxonomies; creating and expiring documents; changing classifications, indexes, taxonomy entries and API key permissions; direct LLM queries; agent execution and the agent retrieval dry run.
- Unchecked operations. Reads, searches and deletes.
- Workers. Each worker checks the expiry date before each batch. After the expiry, the worker logs
The license is no longer valid: the worker stops; queued documents wait for a renewed licenseand stops withError: "License check failed: Expired license". Documents that are not yet processed remainpending.
A refused operation returns HTTP 403 with one of the following messages. Errors describes each message.
| Message | Condition |
|---|---|
Invalid license: Expired | The license has expired |
Invalid license: Exceeded("<type>") | For pipelines, text splitters, embedding models, agents, LLMs, API keys and taxonomies: a cached count exceeds the limit for the named type, and every checked operation fails, whatever the object type. For Documents and Fragments: the count has reached the limit, and requests that add documents fail. |
License limits exceeded for <type> | Creating one more object of the type would exceed the limit |
The API server counts objects in the following ways:
| Object types | Count | Refresh |
|---|---|---|
| Pipelines, text splitters, embedding models, agents, LLMs, API keys, taxonomies | Exact count | At API server startup and every 10 minutes; each create also counts exactly |
| Documents, fragments | Live row counts from the PostgreSQL statistics, without ANALYZE | At API server startup and every 10 seconds |
Deleting objects lowers the counts at the next refresh. Restarting the API server refreshes every count at once. Documents accepted before a count reaches the limit are processed in full, so the counts can pass the limit by the documents added within one refresh. The workers keep no counts and check only the expiry date.
The queue keeps each processing job for 24 hours after the document is submitted. When a renewed license is deployed within that time, the restarted workers process the queued documents. Documents whose jobs were removed from the queue remain pending, and the client application submits these documents again, as Ingest documents reliably describes.
Troubleshooting
Installation or upgrade stopped at the license check
- Symptoms.
helm installorhelm upgradeof the application release fails with a failed pre-install or pre-upgrade hook, and the Jobfoundation4ai-api-server-license-checkshowsFailed. - Diagnosis.
kubectl logs -n foundation4ai job/foundation4ai-api-server-license-checkshowsChecking for a valid license...followed byMissing,Invalid,ExpiredorThe system id for this license version could not be computed. - Cause. The license in
foundation4ai-secretsis empty or still the placeholder, does not match the system ID or has expired, or the database user cannot runpg_control_system(). - Resolution. Obtain a license for the system ID in the log, set the license in
foundation4ai.secrets.env, apply the Secret, and install or upgrade the application release again. For an unavailable system ID, grant the permission as Database describes. - Actions to avoid. Deleting the failed Job before the system ID is recorded. The log of the Job is the only source of the system ID during the first installation.
API server or workers exiting with a license error
- Symptoms. The
serverorworkercontainers restart repeatedly, and the logs reportLicense check failed. - Diagnosis.
kubectl logs -n foundation4ai deploy/foundation4ai-api-server -c server --previousshows whether the message ends withInvalid licenseorExpired license, and shows the warning with the system ID.kubectl logs -n foundation4ai deploy/foundation4ai-api-server-worker -c worker --previousshows the same message for a worker. - Cause. The license is not valid for the database. The database was replaced or restored with a new system ID, or the license expired, which stops the workers and every restarted pod.
- Resolution. Obtain a license for the system ID in the warning and follow License renewal from step 2.
- Actions to avoid. Recreating the database or reinstalling the core release to clear the error. A new database has a new system ID and needs a new license as well.
License rejected for a license issued for the installation
- Symptoms.
license detailsor the license check printsInvalidfor a license that the Foundation4 provider issued for this installation. - Diagnosis.
kubectl exec -n foundation4ai deploy/foundation4ai-api-server -c server -- ./foundation4ai license system-idshows the current system ID. The system ID sent to the provider is compared with the current value. - Cause. The system ID changed after the license request: the database was moved to another cluster, restored under another name, or
database.schemachanged. For licenses of versions 1 and 2, a recreated database or a new schema owner also changes the system ID. A license copied with missing or extra characters also reads as invalid. - Resolution. Copy the license again without line breaks. When the system ID differs, request a license for the current system ID.
- Actions to avoid. Changing
database.schemato match a system ID. The schema setting selects the tables that Foundation4 reads, and a changed schema produces another system ID.
Writes refused with HTTP 403 while the license is current
- Symptoms. Create and update requests return HTTP 403 with
Invalid license: Exceeded("<type>"), although the license has not expired. - Diagnosis.
GET /license, as shown in License renewal, returns the limit and the number of objects in use for each object type.statusnames the exceeded limit. - Cause. For a configuration object type, such as pipelines or API keys, the cached count exceeds the license limit, and every checked operation fails. For documents and fragments, the count has reached the limit, and only requests that add documents fail.
- Resolution. Delete objects of the named type and restart the API server to refresh the counts, or install a license with higher limits.
- Actions to avoid. Creating objects of other types to test the license. Every checked operation fails while the count of a configuration object type exceeds the limit.
Documents pending after a license renewal
- Symptoms. Documents submitted before or during the expiry remain
pendingafter the renewal. - Diagnosis. The client application finds the documents concerned, as described in Pending documents.
kubectl get pods -n foundation4aishows whether the worker pods run since the renewal. - Cause. Workers stop after the expiry, and the queue removes each job 24 hours after the document was submitted. Documents whose jobs were removed are no longer processed.
- Resolution. The client application submits the documents again, as described in Ingest documents reliably.
- Actions to avoid. Restarting the workers to process removed jobs. Jobs removed from the queue are not processed again after a restart.