CF app JVM method exception
CF app JVM method exception is a Cloud Foundry chaos fault that forces a specific JVM method (class.method) inside a running Java app to throw the exception class you specify in exception. The fault lasts for duration seconds, after which the method behaves normally again.
Use this fault to validate the application's error-handling paths: try/catch coverage, exception-mapping, retry budgets, dead-letter queues, and circuit-breaker trips. It is also useful for testing how upstream consumers handle a known synchronous failure pattern.
If you have not configured the chaos infrastructure yet, go to Quickstart to install the Linux chaos infrastructure and run an experiment end to end.
Use cases
- Catch-block coverage: Confirm exceptions raised by a key method are caught and mapped to the expected user-visible response.
- Retry budgets: Validate the caller does not retry indefinitely on a permanent-looking exception.
- Circuit-breaker behavior: Confirm the breaker opens after the configured threshold.
- Observability: Verify the exception surfaces in logs and metrics with the right severity and tags.
Before you begin
- Chaos infrastructure: A Linux chaos infrastructure (LCI) installed in one of the supported deployment models.
- CF and BOSH credentials: The LCI host has
CF_*,UAA_SERVER_ENDPOINT, andBOSH_*credentials configured. - Target identifiers: You know the
organization,space,app, and theboshDeployment. - Java app: The target app exposes a JVM agent on
port(default9091). - Method signature: You know the fully qualified class name and method name to target. Overloaded methods are matched by name; restrict the experiment in test environments to avoid false targets.
Supported environments
| Platform | Support status |
|---|---|
| Java apps deployed to Cloud Foundry | Supported |
| Non-Java workloads | Not supported |
Permissions required
| Action | Requirement |
|---|---|
| List apps the CF user can access | SpaceDeveloper, SpaceAuditor, OrgManager, or OrgAuditor; scopes cloud_controller.read or cloud_controller.admin |
| List BOSH deployments | BOSH user with bosh.read scope |
| SSH to a Diego cell via BOSH | BOSH UAA token with bosh.ssh or bosh.admin scope |
| Attach the JVM agent to the target container | Operator with sudo or root on the cell host |
Authentication
| Layer | Where to provide | Tunables |
|---|---|---|
| Cloud Foundry API + BOSH director | /etc/linux-chaos-infrastructure/cf.env on the LCI host | CF_API_ENDPOINT, CF_USERNAME, CF_PASSWORD, UAA_SERVER_ENDPOINT, BOSH_CLIENT, BOSH_CLIENT_SECRET, BOSH_CA_CERT, BOSH_ENVIRONMENT |
vSphere (only when faultInjectorLocation: vSphere) | /etc/linux-chaos-infrastructure/vsphere.env | GOVC_URL, GOVC_USERNAME, GOVC_PASSWORD, GOVC_INSECURE, VM_NAME, VM_USERNAME, VM_PASSWORD |
Fault tunables
Required parameters
| Tunable | Description | Default |
|---|---|---|
deploymentModel | LCI placement model. One of model-1 or model-2. | (required) |
organization | CF organization that owns the app. | (required) |
space | CF space within the organization. | (required) |
app | Java app whose method is targeted. | (required) |
class | Fully qualified class name (for example, com.example.OrderService). | (required) |
method | Method on class to instrument. | (required) |
exception | Fully qualified exception class to throw (for example, java.lang.RuntimeException). | (required) |
Chaos parameters
| Tunable | Description | Default |
|---|---|---|
port | JVM agent port inside the container. | 9091 |
javaHome | Value of JAVA_HOME. Not required if the Java binary is on the container's PATH. | "" |
instanceAffectedPercentage | Percentage of instances to target. 0 targets exactly one. | 0 |
boshDeployment | BOSH deployment name. Required for deploymentModel: model-2. | "" |
faultInjectorLocation | local or vSphere. Required for deploymentModel: model-2. | local |
faultInjectorPort | Local port used by the fault-injector. | 50320 |
duration | Total chaos duration. | 30s |
skipSSLValidation | Skip SSL validation when calling CF APIs. | false |
rampTime | Wait period in seconds before and after the fault. | 0 |
Tunables that apply to every fault are documented in common tunables for all faults.
Fault execution in brief
Authenticates to Cloud Foundry and BOSH, locates the target app instance(s), attaches an agent to the JVM via the debug port, and installs a rule that makes every call to class.method throw an instance of exception. The rule is removed when duration elapses.
Expected behavior during fault execution
- Every invocation of the targeted method throws the configured exception until the rule is removed.
- Callers experience whatever error path your application defines for that exception (HTTP 500, mapped 4xx, retry-then-fail, circuit-breaker open, and so on).
- After the fault ends, the method returns to its normal implementation.
Signals to watch
- Caller-side error rate: Use an HTTP probe on an endpoint that calls the targeted method.
- Exception logs: Confirm the configured exception appears in the app's logs with the expected severity.
Recovery and cleanup
- The instrumentation is removed when
durationelapses, restoring normal behavior. - If the experiment is aborted, the fault still attempts to remove the rule before exiting.
Limitations
- Matches methods by name only. Overloaded methods on the same class throw the exception regardless of signature.
- The fault does not synthesise a stack trace; the exception originates inside the JVM agent.
Troubleshooting
CF app JVM method exception fails with 'class or method not found' in Harness Chaos Engineering
Confirm the fully qualified class name (with package) and method name match the loaded code exactly. Class names are case-sensitive. Use cf ssh <app> -c 'jcmd 1 GC.class_histogram' to inspect what is loaded.
Method still returns normally after the fault starts
The targeted method may not have been called during the chaos window, or it was JIT-inlined before the agent attached. Generate traffic through the endpoint that calls the method, or restart the app instance before re-running.
Common configurations
Throw a custom exception
apiVersion: litmuchaos.io/v1alpha1
kind: LinuxFault
metadata:
name: cf-app-jvm-method-exception
labels:
name: app-jvm-method-exception
spec:
cfAppJVMChaos/inputs:
duration: 30s
deploymentModel: model-2
faultInjectorLocation: vSphere
app: cf-app
organization: dev-org
space: dev-space
boshDeployment: cf
class: com.example.OrderService
method: placeOrder
exception: com.example.OrderRejectedException
CF secrets
The following Cloud Foundry secrets reside on the same machine where the chaos infrastructure is executed. These secrets are provided in the /etc/linux-chaos-infrastructure/cf.env file in the following format:
CF_API_ENDPOINT=XXXXXXXXXXXXXXXXXXX
CF_USERNAME=XXXXXXXXXXXXXXXXXXXXXXX
CF_PASSWORD=XXXXXXXXXXXXXXXXXXXXXXX
UAA_SERVER_ENDPOINT=XXXXXXXXXXXXXXX
BOSH_CLIENT=XXXXXXXXXXXXXXXXXXXXXXX
BOSH_CLIENT_SECRET=XXXXXXXXXXXXXXXX
BOSH_CA_CERT=XXXXXXXXXXXXXXXXXXXXXX
BOSH_ENVIRONMENT=XXXXXXXXXXXXXXXXXX
If the secrets file is not provided, the secrets are attempted to be derived from environment variables and the config file by the fault-injector.
| ENV name | Description | Example |
|---|---|---|
| CF_API_ENDPOINT | API endpoint for the CF setup | https://api.system.cf-setup.com |
| CF_USERNAME | Username for the CF user | username |
| CF_PASSWORD | Password for the CF user | password |
| UAA_SERVER_ENDPOINT | API endpoint for the UAA server for the CF setup | https://uaa.system.cf-setup.com |
| BOSH_CLIENT | Used by the bosh CLI, the BOSH client | admin |
| BOSH_CLIENT_SECRET | Used by the bosh CLI, the BOSH client secret | UBu9Fu3oW35sO6fw12auPH76gsRTy7 |
| BOSH_CA_CERT | Used by the bosh CLI, the file path for BOSH CA certificate | /root/root_ca_certificate |
| BOSH_ENVIRONMENT | Used by the bosh CLI, the BOSH environment | bosh.corp.local |
Fault injector ENVs and config file
If /etc/linux-chaos-infrastructure/cf.env file is not provided, fault-injector attempts to derive the secrets from environment variables or a configuration file. Any secret that is re-declared will be overridden in the following order of decreasing precedence:
/etc/linux-chaos-infrastructure/cf.envfile- Environment variables
- Configuration file
The configuration file should be provided at /etc/linux-chaos-infrastructure/cf-fault-injector.yaml:
cf-api-endpoint: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
username: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
password: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
uaa-server-endpoint: XXXXXXXXXXXXXXXXXXXXXXXXXX
bosh-client: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
bosh-client-secret: XXXXXXXXXXXXXXXXXXXXXXXXXXX
bosh-ca-cert: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
bosh-environment: XXXXXXXXXXXXXXXXXXXXXXXXXXXXX
A mapping between all the three formats for providing the secrets is as follows:
| cf.env | ENV | cf-fault-injector.yaml |
|---|---|---|
| CF_API_ENDPOINT | CF_API_ENDPOINT | cf-api-endpoint |
| CF_USERNAME | USERNAME | username |
| CF_PASSWORD | PASSWORD | password |
| UAA_SERVER_ENDPOINT | UAA_SERVER_ENDPOINT | uaa-server-endpoint |
| BOSH_CLIENT | BOSH_CLIENT | bosh-client |
| BOSH_CLIENT_SECRET | BOSH_CLIENT_SECRET | bosh-client-secret |
| BOSH_CA_CERT | BOSH_CA_CERT | bosh-ca-cert |
| BOSH_ENVIRONMENT | BOSH_ENVIRONMENT | bosh-environment |
vSphere secrets
These secrets are provided only if vSphere is used as the deployment platform for CF.
The following vSphere secrets reside on the same machine where the chaos infrastructure is executed. These secrets are provided in the /etc/linux-chaos-infrastructure/vsphere.env file in the following format:
GOVC_URL=XXXXXXXXXXXXXXXXXXXXXX
GOVC_USERNAME=XXXXXXXXXXXXXXXXX
GOVC_PASSWORD=XXXXXXXXXXXXXXXXX
GOVC_INSECURE=XXXXXXXXXXXXXXXXX
VM_NAME=XXXXXXXXXXXXXXXXXXXXXXX
VM_USERNAME=XXXXXXXXXXXXXXXXXXX
VM_PASSWORD=XXXXXXXXXXXXXXXXXXX
| ENV Name | Description | Notes |
|---|---|---|
| GOVC_URL | Endpoint for vSphere | For example, 192.168.214.244 |
| GOVC_USERNAME | Username for the vSphere user | For example, username |
| GOVC_PASSWORD | Password for the vSphere user | For example, password |
| GOVC_INSECURE | Skip SSL validation for govc commands | For example, true |
| VM_NAME | Name of the vSphere VM where the fault-injector utility is installed | For example, cf-vm |
| VM_USERNAME | Username for the VM guest user | For example, root |
| VM_PASSWORD | Password for the VM guest user | For example, password |
Related faults
- CF app JVM method latency: Make the same method slow instead of failing.
- CF app JVM modify return: Make the method return a different value instead of throwing.