Skip to main content
Version: Spectra Analyze 9.7.1

Troubleshooting

This guide covers common issues with Spectra Analyze and the steps to resolve them.

File upload fails or hangs​

Symptom

The upload progress bar in the header stalls or the browser shows no response after selecting a file via the Submit button. The upload may fail silently, or the browser displays a network error.

Cause

The most common causes are:

  • The file exceeds the configured maximum upload size.
  • The browser tab was navigated away from or refreshed during upload, which interrupts the transfer.
  • A network timeout or proxy between the browser and the appliance terminated the connection.
  • Disk space on the appliance is critically low, causing the upload to be rejected at the server.

Solution

  1. Check the appliance's configured maximum file size limit under Administration > Configuration > System and compare it to the file you are trying to submit. Files larger than this limit are rejected with an HTTP 413 error.
  2. Do not navigate away from the page or refresh the browser tab while an upload is in progress. The upload status bar in the header indicates active transfers.
  3. If you are uploading over a proxy or VPN, check that the proxy is not terminating idle connections prematurely. Increase the proxy timeout or upload directly if possible.
  4. Check available disk space on the appliance using the Health Status Indicator or the Administration > System Status page. See Storage space warning for remediation steps.
  5. For large files, use the Submissions API directly with a tool like curl to bypass browser limitations:
curl -X POST https://<appliance>/api/uploads/v1/samples/ \
  -H "Authorization: Token <your-api-token>" \
  -F "file=@/path/to/large-file.exe"

File stuck in "Processing" status​

Symptom

A submitted file remains in the Processing state on the Search & Submissions page for an extended period (more than 15–30 minutes for typical files) and never transitions to a classified state.

Cause

  • The appliance analysis queue is backed up due to a large number of submissions.
  • A Spectra Core analysis instance has become unresponsive processing an unusually complex or deeply nested archive.
  • The appliance has insufficient CPU or memory resources to keep up with the current submission rate.

Solution

  1. Check the Health Status Indicator for CPU, memory, and queue size warnings. Navigate to Administration > System Status for a detailed breakdown.
  2. If the queue is congested, reduce the rate of new submissions and allow existing jobs to drain.
  3. Check the appliance system logs for errors related to analysis workers. If an individual analysis instance is hung, the appliance will typically restart it automatically.
  4. For files that are persistently stuck, try resubmitting the file after the queue clears. You can also use the Reanalyze API to trigger reanalysis:
curl -X POST https://<appliance>/api/samples/v1/<sha1>/analyze/ \
  -H "Authorization: Token <your-api-token>"
  1. If the issue persists across multiple files, contact ReversingLabs Support with system logs.

Classification result is unexpected (false positive or false negative)​

Symptom

A file is classified as malicious when it is known to be clean (false positive), or a known malicious file is classified as goodware or receives a low risk score (false negative).

Cause

  • A custom YARA rule with overly broad pattern matching is triggering on clean files.
  • The file is new and has not yet been seen by enough classification sources to produce a confident verdict.
  • The classification was manually overridden by another user on the appliance.
  • The file is a compressed or packed variant not yet in the threat database.

Solution

  1. Review the Classification Reason in the Report Summary Header to identify which classifier produced the final verdict.
  2. If the classification originates from a YARA rule, navigate to the YARA page and review the matching ruleset. Tighten the rule conditions to reduce false positives. See Interpreting Analysis Results for guidance on evaluating classification confidence.
  3. Check whether a user override is in effect. The classification sources table on the sample details page shows if a manual override is present.
  4. For false negatives on known malware, check whether Spectra Intelligence enrichment is configured and reachable (see Cannot connect to Spectra Intelligence for enrichment). Intelligence feed data significantly improves classification confidence.
  5. If the sample is a known false positive, apply a classification override through Administration > Configuration or use the Set Classification API.
  6. Submit persistent false positives or false negatives to ReversingLabs for analyst review at support@reversinglabs.com.

Cannot log in / authentication error​

Symptom

Attempting to log in to the Spectra Analyze web interface returns "Invalid credentials", "Account locked", or redirects back to the login page without an error message.

Cause

  • Incorrect username or password.
  • The user account has been disabled or locked after repeated failed login attempts.
  • An SSO or LDAP integration is misconfigured, causing authentication to fail silently.
  • The session cookie is stale or the browser has cached an old session.

Solution

  1. Verify you are entering the correct credentials. Passwords are case-sensitive.
  2. Clear browser cookies and cache, then retry the login.
  3. If the account is locked, an administrator can unlock it under Administration > Users. See Users.
  4. If LDAP or SSO integration is in use, verify the configuration under Administration > Configuration. Confirm that the LDAP server is reachable from the appliance and that bind credentials are correct.
  5. If you have lost administrator access entirely, contact ReversingLabs Support to arrange account recovery.

Appliance shows license warning or expiry​

Symptom

A banner appears in the interface warning that the license is expiring soon or has already expired. The Health Status Indicator shows a red icon. Certain features or API endpoints may become unavailable.

Cause

  • The appliance license has reached or passed its expiration date.
  • A new license file has been issued but not yet applied to the appliance.
  • The appliance cannot reach the ReversingLabs license server for validation (for cloud-validated licenses).

Solution

  1. Navigate to Administration > Configuration > Licensing to view the current license status and expiration date. See Licensing.
  2. If you have received a new license file, upload it through the licensing page.
  3. If the license appears valid but the warning persists, verify that the appliance can reach the ReversingLabs license server. Check for firewall rules blocking outbound HTTPS traffic.
  4. Contact your ReversingLabs account manager or support@reversinglabs.com to request a license renewal.

API returns 401 Unauthorized​

Symptom

API requests return:

{"detail": "Invalid token."}

or

HTTP/1.1 401 Unauthorized

Cause

  • The API token is missing from the request headers.
  • The token has been revoked or has expired.
  • The token is being passed incorrectly (wrong header name or format).

Solution

  1. Confirm that every API request includes the Authorization header with the correct token format:
curl -H "Authorization: Token <your-api-token>" \
  https://<appliance>/api/samples/v1/
  1. Verify that the token is still valid. Navigate to User Profile > API Token in the Spectra Analyze interface, or check Administration > Tokens if you manage tokens for multiple users. See Tokens.
  2. If the token was recently regenerated or revoked, update all integrations and scripts that use the old token.
  3. Check that the token belongs to a user account that is still active and has not been disabled.

API returns 403 Forbidden​

Symptom

API requests return:

HTTP/1.1 403 Forbidden
{"detail": "You do not have permission to perform this action."}

Cause

  • The authenticated user's role does not grant access to the requested endpoint or resource.
  • A per-user or per-group permission restriction is in place for the specific operation (for example, deleting samples or accessing administration endpoints).

Solution

  1. Check the user's assigned role under Administration > User Roles. See User Roles for a full list of permissions associated with each role.
  2. If the operation requires elevated privileges, ask an administrator to assign the appropriate role or a higher-privilege role to the user.
  3. If the 403 is returned for a specific resource (for example, a private sample), check whether the sample's visibility settings restrict access.

Slow analysis performance​

Symptom

Files take significantly longer than expected to complete analysis. The queue displayed in the Health Status Indicator is consistently non-zero. Analysis that normally completes in seconds takes minutes.

Cause

  • The appliance is receiving more submissions than its current Spectra Core capacity can handle.
  • Large or deeply nested archives (for example, multi-layer ZIP files) are consuming disproportionate analysis time.
  • CPU or memory resources on the appliance are under heavy load from other processes.
  • The appliance hardware does not meet recommended specifications for the current submission volume.

Solution

  1. Check CPU and memory utilization via Administration > System Status or the Health Status Indicator. Look for sustained CPU above 90% or memory above 85%.
  2. Review the configured system health thresholds under Administration > Configuration > System Health and adjust alert thresholds to get earlier warnings.
  3. Identify if specific file types (large archives, firmware images) are consistently slow. Consider rate-limiting submission of such files during peak periods.
  4. If the appliance is persistently under-resourced, consider adding a Spectra Detect Worker cluster and connecting it via Spectra Detect Manager to offload processing.
  5. Review the platform requirements to confirm the appliance meets minimum hardware specifications for the current submission rate.

Storage space warning​

Symptom

The Health Status Indicator shows a red icon with a disk-related warning. The hover tooltip or System Status page displays a message similar to:

Disk usage: 94% — threshold exceeded

New file uploads may be rejected.

Cause

  • The appliance disk has accumulated a large number of stored samples and analysis results.
  • Log files or system backups have consumed available space.
  • The configured disk usage threshold has been set too conservatively relative to actual growth patterns.

Solution

  1. Navigate to Administration > Configuration > Backup & Purge to configure automated sample purge policies. Samples older than a specified retention period can be removed automatically. See Backup & Purge.
  2. Run an immediate purge to reclaim space: navigate to the Backup & Purge page and trigger a manual purge.
  3. If log files are consuming space, rotate or archive them per your appliance OS procedures.
  4. Adjust the disk usage alert threshold under Administration > Configuration > System Health if the current threshold triggers too early for your capacity.
  5. If disk space is chronically insufficient, consider expanding the appliance storage volume or archiving older samples externally before deleting them from the appliance.

Cannot connect to Spectra Intelligence for enrichment​

Symptom

The Health Status Indicator shows a red icon. The hover tooltip displays:

Spectra Intelligence: not reachable

Samples on the appliance lack Spectra Intelligence enrichment data such as scanner detections, threat names, or community classifications.

Cause

  • The Spectra Intelligence credentials configured on the appliance are incorrect or have expired.
  • Network connectivity from the appliance to data.reversinglabs.com is blocked by a firewall or proxy.
  • The Spectra Intelligence account has exceeded its quota, causing requests to be rejected with HTTP 429.

Solution

  1. Navigate to Administration > Configuration > Spectra Intelligence and verify that the username and password are correct. Test the connection using the built-in connectivity check.
  2. From the appliance, test outbound connectivity to the Spectra Intelligence API server:
curl -I https://data.reversinglabs.com

If this times out or is refused, check firewall rules and proxy configuration. The appliance must be able to reach data.reversinglabs.com over HTTPS (port 443).

  1. If a proxy is required, configure the proxy address in Administration > Configuration > System or contact your network team to allow direct HTTPS access to data.reversinglabs.com.
  2. Check your Spectra Intelligence quota via the Quota Indicator in the appliance header bar, or via the Customer Usage API. If the quota is exhausted, contact support@reversinglabs.com to review your entitlements.