# Spectra Analyze Troubleshooting — Upload Failures, API Errors & Licensing

> Resolve common Spectra Analyze issues: file upload failures, HTTP 413 errors, classification problems, license warnings, disk space alerts, and API error codes.

# Troubleshooting

This guide covers common issues with [Spectra Analyze](./index.md) 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 > General** and compare it to the file you are trying to submit. Files larger than this limit are rejected with an HTTP 413 error when submitted via the API. When submitted via the GUI, files exceeding the limit display a modal: "File Size Exceeds Spectra Analyze Upload Limit! Analyze large files with Spectra Detect!"
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](./index.md#health-status-indicator) or the **Administration > System Status** page. See [Storage space warning](#storage-space-warning) for remediation steps.
5. For large files, use the [Submissions API](./API%20Documentation/submissions.md) directly with a tool like `curl`:

```bash
curl -X POST https://<appliance>/api/submit/file/ \
  -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](./search-page.md) 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](./index.md#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](./API%20Documentation/reanalyze-api.md) to trigger reanalysis:

```bash
curl -X POST https://<appliance>/api/samples/<sha1>/analyze/ \
  -H "Authorization: Token <your-api-token>" \
  -F "analysis=core"
```

5. If the issue persists across multiple files, contact [ReversingLabs Support](mailto:support@reversinglabs.com) 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](./Sample%20Details/sample-details-summary.md) to identify which classifier produced the final verdict.
2. If the classification originates from a YARA rule, navigate to the [YARA](./yara.md) page and review the matching ruleset. Tighten the rule conditions to reduce false positives. See [Interpreting Analysis Results](./getting-started.md#understanding-the-classification-reason) 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](#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 directly on the sample details page or use the [Set Classification API](./API%20Documentation/set-classification-api.md). See [Administering classification overrides](./getting-started.md#administering-classification-overrides) for details.
6. Submit persistent false positives or false negatives to ReversingLabs for analyst review at [support@reversinglabs.com](mailto: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 due to failed login attempts, it cannot be manually unlocked by an administrator. The account will automatically unlock after the configured block timeout expires. See [Login Security](./Administration/configuration-update/configuration.md#login-security) for details on the lock duration.
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](mailto:support@reversinglabs.com) 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](./index.md#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](./Administration/configuration-update/licensing.md).
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](mailto:support@reversinglabs.com) to request a license renewal.

---

## API returns 401 Unauthorized

**Symptom**

API requests return:

```json
{"detail": "Invalid token."}
```

or

```http
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, for example:

```bash
curl -X POST https://<appliance>/api/samples/<sha1>/analyze/ \
  -H "Authorization: Token <your-api-token>" \
  -F "analysis=core"
```

2. Verify that the token is still valid by checking **Administration > Tokens** if you manage tokens for multiple users. See [Tokens](./Administration/users-personalization/tokens.md).
3. If the token was recently regenerated or revoked, update all integrations and scripts that use the old token.
4. 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
HTTP/1.1 403 Forbidden
```

```json
{"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](./Administration/users-personalization/user-roles.md) 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 on the **Administration > System Status** page 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](./index.md#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 Indicator** 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](/SpectraDetect/Admin/ManagerSettings/) to offload processing.
5. Review the [platform requirements](/General/DeploymentAndIntegration/PlatformRequirements) to confirm the appliance meets minimum hardware specifications for the current submission rate.

---

## Storage space warning

**Symptom**

The [Health Status Indicator](./index.md#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](./Administration/configuration-update/backup-purge.md).
2. To reclaim space immediately, navigate to **Administration > Configuration & Update > Backup & Purge** and click **Run Purge** to trigger a manual purge according to the configured retention criteria.
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 Indicator** 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](./index.md#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:

```bash
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).

3. If a proxy is required, configure the proxy address in **Administration > Configuration > General** under the proxy settings, or contact your network team to allow direct HTTPS access to `data.reversinglabs.com`.
4. Check your Spectra Intelligence quota via the **Quota Indicator** in the appliance header bar, or via the [Customer Usage API](/SpectraIntelligence/API/CustomerUsage/tca-9999). If the quota is exhausted, contact [support@reversinglabs.com](mailto:support@reversinglabs.com) to review your entitlements.
