JavaCallout policy runtime error troubleshooting

ResourceDoesNotExist

Error Message

Deployment of the API proxy through either the Edge UI or Edge management API fails with this error message:

Error Deploying Revision <var>revision_number</var> to <var>environment</var>
Resource with name <var>ResourceURL</var> and type java does not exist.

Example Error Message

Error Deploying Revision 1 to test
Resource with name myresource.jar and type java does not exist.

Example Error Screenshot

Cause

If the resource specified in the <ResourceURL> element in the JavaCallout policy does not exist at the API proxy, environment, or organization level, then the deployment of the API proxy fails.

Diagnosis

  1. Identify the environment and resource name. You can find this information in the error message. For example, in the following error the environment is test and the resource name used in the <ResourceURL> element is myresource.jar.

    Error Deploying Revision 1 to test
    Resource with name myresource.jar and type java does not exist.
    
  2. Determine the JavaCallout policy that is using the resource identified in step #1 above.

    For example, the following policy specifies the value of <ResourceURL> as myresource.jar, which matches with the value in the error message:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <JavaCallout name="hello-java">
        <ClassName>com.apigeesample.HelloJava</ClassName>
        <ResourceURL>java://myresource.jar</ResourceURL>
    </JavaCallout>
    
  3. Determine if the resource is either part of the API proxy that is failing or uploaded at the environment or organization level. If not, then this is the cause of the error.

    • Navigate to the Resources tab in the Navigator pane of the API proxy editor to view all the resources uploaded at the API proxy level. In this example the API proxy has no resources uploaded.

    • Resources can be available at the environment or organization level. For more information, see Resource files.

      • To determine if the resource exists at the environment level, issue the following API call using curl:
        curl -v -u <strong>email </strong>"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/resourcefiles/java/myresource.jar"

      • To determine if the resource exists on the organization level, issue the following API call using curl, omitting the environment details:
        curl -v -u email "https://api.enterprise.apigee.com/v1/organizations/myorg/resourcefiles/java/myresource.jar"

      If you receive a 404 status code as the response for these APIs, then the resource is missing at both the organization and environment level.

    If the resource is not available at the API proxy, organization, and environment level, the deployment error is returned:

    Resource with name myresource.jar and type java does not exist.
     ```    
    

Resolution

Ensure that the resource specified in the <ResourceURL> element does exist at the API proxy, environment, or organization level. For more information, see Resource files.

To correct the example JavaCallout policy shown above, upload the JAR file at the appropriate level (API proxy, organization, or environment level).

NoResourceForURL

Error Message

Deployment of the API proxy through either the Edge UI or Edge management API fails with this error message:

Error in deployment for environment <var>environment</var>
The revision is deployed, but traffic cannot flow. Could not locate a resource with URL <var>ResourceURL</var>

Example Error Message

Error in deployment for environment test
The revision is deployed, but traffic cannot flow. Could not locate a resource with URL java://myresource.jar

Example Error Screenshot

Cause

This error may occur if resource file is either corrupted or partially uploaded, even though it appears to exist at the API proxy, environment, or organization level.

Diagnosis

  1. Identify the environment and the resource name. You can find this information in the error message. For example, in the following error, the environment name is test and the Resource Name used in the <ResourceURL> element is myresource.jar.

    Error in deployment for environment test
    The revision is deployed, but traffic cannot flow. Could not locate a resource with URL java://myresource.jar
    
  2. Ensure that the resource is uploaded at the API proxy, environment, or organization level. In the example below, you can see that resource myresource.jar is uploaded at the API proxy level.

    Resources can be available at the environment or organization level. For more information, see Resource files.

    To determine if the resource exists at the environment level, issue the following API call using curl:
    curl -v -u <strong>email </strong>"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/resourcefiles/java/myresource.jar"

    To determine if the resource exists at the organization level, issue the following API call using curl, omitting the environment details:
    curl -v -u email "https://api.enterprise.apigee.com/v1/organizations/myorg/resourcefiles/java/myresource.jar"

    If you receive a 404 status code as the response for these APIs, then the resource is missing at both the organization and environment level.

Resolution

  1. If you determine that the resource exists at the API proxy, organization, or environment level, delete the resource and re-upload it, as described in step 2. Otherwise, skip to step 3.
  2. To delete the resource at the API proxy level, navigate to the Resources tab in the Navigator pane of the API proxy editor and click the “X” button next to the resource as shown below.

    To delete resource at the environment or organization level, use the DELETE verb on the API calls that were used previously in diagnosis steps. For example, to delete the resource at the environment level, enter the following command: curl -X DELETE -v -u <strong>email </strong>"https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/resourcefiles/java/myresource.jar"

  3. Upload the JAR file) at the appropriate level (API proxy, organization, or environment level.

  4. If re-uploading the resource doesn’t help, then affected Message Processors need to be restarted. If you are using Apigee Edge in Cloud, contact Apigee Support. If you are a Private Cloud user, see Starting, stopping, restarting, and checking the status of Apigee Edge.

JavaCalloutInstantiationFailed

Error Message

Deployment of the API proxy through either the Edge UI or Edge management API fails with this error message:

Error in deployment for environment <var>environment</var>
The revision is deployed, but traffic cannot flow. Failed to instantiate the JavaCallout Class <var>class_name</var>

Or

Error in deployment for environment <var>environment</var>.
The revision is deployed and traffic can flow, but flow may be impaired. Failed to instantiate the JavaCallout Class <var>class_name</var>

Example Error Message

Error in deployment for environment test
The revision is deployed, but traffic cannot flow. Failed to instantiate the JavaCallout Class my.class

Example Error Screenshot

Cause

Here are typical causes for this error

Cause Description
Missing JAR file The JAR file containing the Java class identified in the error is not uploaded.
Corrupted JAR file The JAR file containing the Java class identified in the error is corrupted/partially uploaded.
Missing Class file The Java class file identified in the error is not part of the JAR file specified in >ResourceURL< or dependent JAR files.
Java Code Issue There is an error in the code, such as a missing constructor, code dependency issue, or other issue.

Common Diagnosis Step

  1. Identify the name of the environment and the Class that failed to be imported. For example in the following error message environment name is test and Class name is my.class:

    Error in deployment for environment test    
    The revision is deployed, but traffic cannot flow. Failed to instantiate the JavaCallout Class my.class
    
    

    Cause: Missing JAR file

Diagnosis

  1. Determine the JAR file that is supposed to contain the class (identified in step #1 above) and that could not be instantiated.
  2. Check if the specific JAR file is uploaded at the API proxy, organization, or environment level. If the JAR file is not uploaded to any of the levels, then go to Resolution.
  3. If the JAR file is uploaded, then go to Cause: Corrupted JAR File.

Resolution

  1. If the JAR file is corrupted or partially uploaded, then rebuild the JAR and upload the JAR file at the appropriate level (API proxy, organization, or environment level).
  2. Redeploy the API proxy.

Cause: Corrupted JAR file

Diagnosis

  1. Determine the JAR file that is supposed to contain the class (identified in step #1 above) which could not be instantiated.
  2. Check if the specific JAR file is corrupted. For example, if you cannot unjar the file because it is corrupted or partially uploaded. If it is corrupted, then go to Resolution.
  3. If the JAR file is not corrupted, then go to Cause: Missing Class File.

Resolution

  1. Rebuild the corrupted JAR file(s) and upload the JAR file) at the appropriate level (API proxy, organization, or environment level.
  2. Redeploy the API proxy.

Cause: Missing Class File

Diagnosis

  1. Check if the specific Java class file (identified in step #1 above) is part of the JAR file specified in >ResourceURL< or any of dependent JAR files.
  2. If the class file does not exist in any of the JAR files, you have determined the cause for the error. Go to Resolution.
  3. If the class file exists in one of the JAR files specified in the JavaCallout policy, then there must be an issue with the Java code or dependent class that’s leading to this error.
    a. If you are a Public Cloud user, contact Apigee Support.
    b. If you are a Private Cloud user, then move to Cause: Java Code Issue.

Resolution

  1. Rebuild the JAR with the missing class file(s) and upload the JAR file at the appropriate level (API proxy, organization, or environment level).
  2. Redeploy the API Proxy.

Cause: Java Code Issue

Diagnostic Steps for Private Cloud Users only

Diagnosis

  1. Check the Message Processor logs (/opt/apigee/var/log/edge-message-processor/system.log and /opt/apigee/var/log/edge-message-processor/configurations.log).
  2. You may see an exception similar to the example below:

    2019-07-05 05:40:13,240 org:myorg env:staging target:/organizations/myorg/apiproxies/MyAPI/revisions/5 action:add context-id: mode: Apigee-Main-53 ERROR CONFIG-CHANGE - AbstractConfigurator.add() : Add null to Step failed, reason: {} 
    com.apigee.kernel.exceptions.spi.UncheckedException: Failed to instantiate the JavaCallout Class <class name> 
    at com.apigee.steps.javacallout.JavaCalloutStepDefinition.newInstance(JavaCalloutStepDefinition.java:116) 
    at com.apigee.messaging.runtime.StepDefinition.getStepDefinitionExecution(StepDefinition.java:218) 
    …<snipped> 
    Caused by: java.lang.reflect.InvocationTargetException: null 
    at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method) 
    at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62) 
    at com.apigee.steps.javacallout.JavaCalloutStepDefinition.access$100(JavaCalloutStepDefinition.java:41) 
    at com.apigee.steps.javacallout.JavaCalloutStepDefinition$CallOutWrapper.initialize(JavaCalloutStepDefinition.java:131) 
    at com.apigee.steps.javacallout.JavaCalloutStepDefinition$CallOutWrapper.<init>(JavaCalloutStepDefinition.java:126) 
    ... 42 common frames omitted 
    Caused by: <Reason> 
    
    ...<snipped>
    
    
  3. Read through the exception carefully to understand the reason for failure. Typically, this may point to some issue in your Java code.

Resolution

  1. Depending on the cause of the failure, you may have to fix the issue in your Java code.
  2. Rebuild the JAR with the missing class file(s) and upload the JAR file at the appropriate level (API proxy, organization, or environment level).
  3. Redeploy the API Proxy.

Upload the JAR file

Ensure that the resource element with all the necessary classes exist at the API Proxy, environment, or organization level. For more information, see Resource files.

  1. To upload a resource at the API proxy level, click + (plus sign) on the Resources tab, then select Import file and upload file from your local machine. The filename should match the >ResourceURL< element, but without the java:// prefix.

  2. If you want a resource to be available for more than one API proxy in the same environment, upload the resource to the environment. You'll need to use the Edge API, as described in Resource files.

    For example, enter the following API call from the local machine to upload the specified file at the environment level:

    curl -v -u email -H "Content-Type: application/octet-stream" \
    -X POST --data-binary @{classes.jar} \
    "http://{mgmt_server}:{port}/v1/organizations/myorg/environments/myenv/resourcefiles?name=myresouce.jar&type=java"
    

    Issue the API call from the same directory as the file.

  3. To make file available for all API proxies within all environments in the organization you can omit the environment details in the basepath. For example:

    curl -v -u email -H "Content-Type: application/octet-stream" \
    -X POST --data-binary @{classes.jar} \
    "http://{mgmt_server}:{port}/v1/organizations/myorg/resourcefiles?name=myresouce.jar&type=java"