We’re implementing automated PX script deployment for change management workflows but encountering ClassNotFoundException during deployment. Our CI/CD pipeline successfully packages the custom JAR with dependencies, but when the PX script executes, it can’t locate our custom utility classes.
Error during deployment:
java.lang.ClassNotFoundException: com.custom.utils.ChangeHelper
at java.net.URLClassLoader.findClass(URLClassLoader.java:381)
at com.agile.px.ActionBase.loadClass(ActionBase.java:267)
The custom JAR is placed in <agile_home>/custom/lib and referenced in the PX script manifest. We’ve verified classpath configuration in the deployment automation script, but the runtime still fails to load dependent classes. Has anyone successfully automated PX deployment with custom JAR dependencies? Our goal is to eliminate manual classpath configuration during each deployment cycle.
The root issue is likely how Agile’s PX classloader handles custom JARs versus standard Java classpath. We resolved similar ClassNotFoundException problems by implementing a three-part deployment strategy:
1. PX Script Deployment Automation with Proper Classpath Management:
Modify your deployment script to register JARs in Agile’s custom classloader:
// Pseudocode - JAR registration steps:
1. Copy custom JAR to <agile_home>/custom/lib/
2. Update agile_px_classpath.properties with new JAR path
3. Register JAR in PX manifest Class-Path attribute
4. Trigger PX classloader refresh via Admin API
// See Agile SDK Guide Section 8.4 for API details
2. Custom JAR Handling in Agile:
The key is understanding that Agile uses a hierarchical classloader. Your automation must:
Place JARs in the correct directory based on scope (global vs PX-specific)
Update both the file system AND Agile’s internal registry
Handle transitive dependencies by either using an uber-JAR or explicitly listing all dependencies
We created a custom Ant task that wraps these operations:
3. Classpath Dependency Management:
Implement dependency validation in your CI/CD pipeline:
Pre-deployment: Scan PX script for imported classes, verify all dependencies present
Post-deployment: Execute a test PX script that instantiates classes from your custom JAR
Rollback capability: Keep previous JAR versions and classpath configs for quick rollback
Our automation also handles the restart timing intelligently. Instead of full server restart, we use Agile’s AdminService API to reload just the PX subsystem:
This approach cut our PX deployment time from 45 minutes (with full restart) to under 5 minutes. The automation eliminated manual classpath editing errors that previously caused 30% of our deployments to fail. Critical success factor: the pre-deployment validation catches dependency issues before they reach production, and the targeted PX reload minimizes system downtime.
For your specific error, verify that your automation script is updating the agile_px_classpath.properties file AND triggering the classloader refresh. The JAR being physically present isn’t enough - Agile’s PX runtime needs to be explicitly told to load it.
This draft is based on general Oracle Agile PLM knowledge. It has not been verified against your specific version and environment. Practitioners: verify the steps and share your experience below.
Check if your automation script is properly registering the JAR in the Agile classpath. The custom JAR needs to be added to both the server classpath AND the PX-specific classpath. We had similar issues where the JAR was physically present but not loaded by the PX classloader.
ClassNotFoundException in PX deployment typically means the manifest file isn’t correctly pointing to dependencies. Your manifest.mf should explicitly list all custom JARs in the Class-Path attribute. Also verify that the JAR naming convention matches exactly what’s referenced in the manifest - case sensitivity matters on Unix systems. We’ve seen deployments fail because automation scripts used different case than the actual JAR filename. Double-check your deployment script’s file copy operation and the manifest Class-Path entry align perfectly.
I’d recommend adding a verification step in your CI/CD pipeline that validates JAR presence and manifest integrity before actual deployment. We built a pre-deployment checker that extracts the manifest, parses Class-Path entries, and confirms each referenced JAR exists in the target location. This caught several issues where automation was copying JARs to wrong directories or with incorrect permissions. The checker runs as part of our Jenkins pipeline and fails the build if dependencies aren’t properly staged.
Have you considered the timing of when Agile loads the custom classpath? Server restart is often required for new JARs to be recognized, but PX scripts might cache classloaders. We implemented a solution where our deployment automation triggers a targeted PX service refresh rather than full server restart, significantly reducing deployment downtime.
Another aspect to investigate is whether your custom JAR has transitive dependencies that aren’t being included. If ChangeHelper depends on third-party libraries like Apache Commons or logging frameworks, those need to be in the classpath too. Use a tool like Maven Dependency Plugin to generate a complete dependency tree, then ensure your automation script deploys ALL required JARs, not just your primary custom JAR. We package everything into a single uber-JAR using Maven Shade Plugin to avoid these dependency resolution issues entirely.
“Confirmed this resolves ClassNotFoundException in our Agile PLM 9.3.6 environment after copying JARs to the custom/lib directory and refreshing the PX classloader.”