Troubleshooting: No Data After Installing Flex Agent Directly

Overview

You've signed up for Contrast CVE Shield Free tier, installed the Flex Agent directly, and connected your first Java application, but it either doesn't show up in Northstar at all, or it shows up with 0 libraries and no data.

This guide walks through what to check, in order, starting with the fastest and easiest methods to try.

Note: Did you install a Contrast agent with the Flex Agent using a Kubernetes Helm Chart  instead? See the Troubleshooting guide for your installation method for details.

Prerequisites

• A CVE Shield account with an agent installed.

• A Java application you can connect.

• Access to the host or VM where your application is running.

Step-by-Step Instructions

1. Send some traffic to your application

Northstar doesn't show library or code data until it sees your application actually running. Open your application in a browser, or hit any URL it responds to, and wait about a minute.

If you don't have an easy way to generate traffic yet, a single request to any page or endpoint is enough to get things started.

If you’d rather script it:

curl -s -o /dev/null -w "%{http_code}\n" http://<app-hostname>/<some-endpoint>

2. Give it a few minutes, then check again

After your first request, it can take a short time for data to appear. Refresh the CVEs page, and check Explorer > Contrast Graph or Administration > Agent management if the CVE Shield table is still empty.

If you still see nothing after a few minutes, move on to the checks below.

3. Check your application limit (422 error)

CVE Shield Free tier supports up to 2 applications and 12 services total. If you're at that limit, a new application won't report data. You'll usually see an upgrade prompt in the UI, and the agent log will show a 422 Application limit reached entry (see the next step for how to view the log).

Go to Explorer > CVEs to check your current count against the limit shown at the top of the page. If you're over, archive or delete unused applications left over from prior test runs, then restart your application. See “Force a fresh attempt after any fix” below for the exact command

4. Search the Community forum

Check the Gather Community forum (linked from your account dropdown) for your exact symptom. This is often the fastest way to confirm what's going on and what fixes it for others.

5. Check your credentials (401 error)

The agent's log lives at /contrast/data/logs/contrast_agent.log by default. To view it:

tail -50 /contrast/data/logs/contrast_agent.log

If the log is long, filter for known signal phrases instead of scrolling:

grep -iE "error|fail|limit|401|403|422|successfully created|standalone mode" /contrast/data/logs/contrast_agent.log

A standalone mode warning about the application name being ignored is usually cosmetic, as long as a successful registration line appears further down the log — confirm the app shows up in Northstar under the name you expect, not as null.

If it shows 401 Unauthorized or “no longer authorized,” your connection token or API key is stale, revoked, or was rotated elsewhere. 

Generate a fresh credential from your agent key settings, update it wherever the agent reads it from, and restart your application.

6. Confirm the agent process is running and attached

If none of the checks above turned up anything, confirm the agent service and your application are both up:

1. Confirm the Flex Agent service is running: sudo systemctl status contrast-flex-agent. 
   If your target process runs inside a container rather than directly on the host, check sudo systemctl status contrast-flex-docker instead.
2. Confirm your application process is up and running: ps aux | grep <your-app-process-name>
3. Confirm auto-attach is engaged: run contrast-flex --help to check auto-attach status. If it's disabled, manually attach with contrast-flex attach <process-id> (you can get the PID from the ps aux command above).

If your application was already running before you installed the Flex Agent, it won't get instrumented until that process restarts. Installing the service doesn't retroactively attach to already-running processes.

7. Force a fresh attempt after any fix

Actions like a new credential, a freed-up slot, a fixed label don’t take effect on a process that's already running. Whatever you fixed, restart to make it stick:

Run sudo systemctl restart <your-app-service> to restart the application process itself, not the Flex Agent service. Alternatively, stop and manually restart it if there's no managed service wrapping it, then confirm agent attachment is enabled before moving on.

Advanced Troubleshooting Steps

Check the agent's connection info

Run java -jar contrast.jar info. If any returned field is null, your token or API key isn't set correctly. Reinstall using the install wizard's provided key/token.

Run the built-in connectivity check

Run java -jar contrast.jar diagnostic. This checks whether the agent can resolve DNS and reach Northstar, and flags network, proxy, or TLS issues.

Turn on debug logging

Still stuck? Turn on CONTRAST__AGENT__LOGGER__LEVEL=DEBUG for more detail (use CONTRAST__AGENT__LOGGER__STDOUT=true if you don't have easy access to log files), restart, and check the log again for the 401/422 entries above.

Still no errors at all? 

The agent likely hasn't reached the point of registering yet. Wait a bit longer, then check network connectivity to your organization's agent URL.

Expected Outcome

Your application appears in Explorer > Contrast Graph with library data, and Issues begins showing CVE data as it is detected.

Escalation path

• Free: Post your error message and the steps you've tried in the Gather Community forum. The first time you visit, you need to create an account.