Skip to main content

Troubleshooting

Common issues when installing, configuring, and running com.candescent.forge:di-java-sdk and the Java examples.

Dependency not found​

Could not find artifact com.candescent.forge:di-java-sdk:jar:1.0.0

Fix:

  1. Confirm the dependency is in your pom.xml with the correct coordinates (com.candescent.forge:di-java-sdk)
  2. Ensure your build tool can reach Maven Central
  3. Run mvn dependency:resolve to refresh the local cache

Java version mismatch​

class file has wrong version

Fix: Use Java 17 or later. Check your version with java -version and update your JAVA_HOME if needed.

Authentication errors (401)​

  • Verify CANDESCENT_CLIENT_ID and CANDESCENT_CLIENT_SECRET match the app in the Developer Console
  • Confirm CANDESCENT_INSTITUTION_ID matches the credentials issued to you
  • For staging, set CANDESCENT_ENVIRONMENT=stage (or Environment.STAGE in code)
  • If using a static bearer token, ensure it has not expired

See Installation and the Getting Started quickstart guides.

hostUserId and loginId mutually exclusive​

Parameters hostUserId and loginId are mutually exclusive

Pass only one user identifier per request — either hostUserId or loginId, not both.

Examples: credentials not set​

Examples read CANDESCENT_* environment variables at runtime. Export them in your shell before running:

Bash
export CANDESCENT_CLIENT_ID=your-client-id
export CANDESCENT_CLIENT_SECRET=your-client-secret
export CANDESCENT_INSTITUTION_ID=your-institution-id
cd examples/java
mvn exec:java -Dexec.mainClass="com.candescent.examples.AccountsExample"

ErrorHandlingExample fails in batch runner​

ErrorHandlingExample is intentionally excluded from the batch runner because it triggers expected API errors. Run it individually:

Bash
cd examples/java
mvn exec:java -Dexec.mainClass="com.candescent.examples.ErrorHandlingExample"

Rate limiting (429)​

The SDK retries 429 responses automatically (up to three attempts). If you still receive RateLimitException, check getRetryAfter() and back off before manually retrying.

Connection errors​

  • Confirm CANDESCENT_ENVIRONMENT is set correctly (sandbox, stage, or production)
  • Check that outbound HTTPS (port 443) is not blocked by a firewall or corporate proxy
  • If behind a proxy, configure your JVM proxy settings or use the baseUrl option in ClientConfig

Client used after close()​

Calling client.close() revokes tokens and releases the client. Any API call made afterwards will fail.

Fix: Create a new CandescentClient instance if you need to make further calls after closing.

Null fields in responses​

Optional fields in the OpenAPI spec are omitted from responses when not present — the SDK reflects that exactly.

Fix: Check for null before accessing response fields:

int count = accounts.getAccounts() != null ? accounts.getAccounts().size() : 0;

Check the API Reference to confirm which fields are always present vs optional.

Pagination returns no results on subsequent pages​

Cause: Passing a page offset beyond the total result count.

Fix: Use PageIterator which handles page advancement and termination automatically. If iterating manually, check totalElements or totalPages in the first response before advancing.

Still stuck?​