`cf push` fails with "An unknown error occurred" when using large environment variables

Products

• VMware Tanzu Application Service

Issue/Introduction

Running cf push with a large number of environment variables or very long strings (e.g., certificates, keys, or large JSON blobs) fails. The CLI returns a generic error: "An unknown error occurred" or "CF-DatabaseError".

Cause

 

The Cloud Controller Database (CCDB) stores app environment variables in a single column (a TEXT type in MySQL).

1. Storage Limit: A MySQL TEXT column has a hard limit of 65,535 bytes (64 KB).

2. Encryption Overhead: Cloud Foundry encrypts environment variables. The combination of JSON stringification, Base64 encoding, etc used in the encryption process typically adds ~30-40% overhead.

3. Result: While your raw manifest text might only be 40 KB, the resulting encrypted string exceeds the 64 KB database limit, causing the database to reject the record.

 

Resolution

Option 1: Use User-Provided Service Instances (CUPS) 

Instead of env variables, move large data into a service binding. Data in VCAP_SERVICES is stored in separate tables (like service_bindings or user_provided_service_instances), which often support much larger payloads (up to 1 MB in many foundations).

cf cups my-large-config -p '{"key": "very-long-value-here"}'
cf bind-service my-app my-large-config

Option 2: Mount a Configuration File

Include large configurations (like .json or .yml files) directly in your application code package. Use your application logic to read these files from the local file system at runtime instead of relying on the OS environment.

Option 3: Use CredHub

For sensitive data like private keys or certificates, store the credentials in CredHub. You can then reference them in your manifest using the ((variable_name)) syntax. The platform will inject these at runtime, keeping the Cloud Controller database "lean."