Imaging Errors & Warnings

This dashboard consolidates imaging failures and warnings so administrators and support engineers can investigate what went wrong, how often, and where. It covers three areas: document-level imaging errors (including the categories of error), agent-level errors and exceptions emitted by the imaging agents, and imaging warnings (such as cut-off text/images, table splits, malformed RTF, and encoding mismatches). Trend charts show how errors and warnings move over time, summary tables break them down by workspace and file type, and raw-data tables provide row-level detail with jump-links into Discover for deep investigation.

The Imaging Errors & Warnings dashboard is available in Relativity Server 2026 and later and is the Errors & Warnings sub-tab of the Imaging suite. Its imaging panels depend on imaging OpenTelemetry (OTEL) metrics, and its agent panels additionally depend on imaging agent logs flowing into the logs-* indices. For availability requirements, prerequisites, dashboard navigation, and the shared time-range and KQL filter controls, see Imaging Overview. If the dashboard loads empty, the likeliest causes are that no imaging activity occurred in the selected time range, or telemetry is not reaching the Elastic/Kibana stack.

Dashboard Controls

This dashboard adds a native controls filter bar for error/warning investigation. Four option-list controls let you scope the imaging panels interactively:

Workspace ID
Imaging Set ID
Job Status - the imaging job's current processing stage. The dropdown lists the raw imaging job-status codes (Created, PickedUpByAgent, SubmittedToInvariant, and so on); for what each code means, see the Job Results Status column reference on the Imaging Overview dashboard. The same raw codes appear in the Job Status column of the Raw Error Data table below.
Profile Type (the imaging method - Basic or Native)

The controls operate on imaging OTEL fields, which do not exist in the agent-log indices. The three agent panels (Agent Errors Over Time, Agent Exceptions by Type, Agent Error Logs) are intentionally configured to ignore these controls so they stay populated while you filter the imaging metric panels.

Document Errors

Imaging Errors & Warnings - errored documents trend and raw error data

Errored Documents Over Time - A time-bucketed line chart of errored documents. Hover over a point to see the count for that time bucket; empty buckets show "No data". Use it to see when error spikes occurred.
Raw Error Data - A row-level table of jobs that produced at least one errored document. Columns include Correlation Id, Host, Process, Job Status, Latest Timestamp, Workspace ID, Imaging Set ID, Errored Documents, Password Protected, Type Not Supported, and Total Documents. Identifier cells (Correlation Id, Workspace ID, Imaging Set ID) render as jump-links that open a filtered Discover view scoped to that value for deep investigation.

Toggle dependency: The Password Protected and Type Not Supported columns (and the related "Real vs Expected" split on Imaging Overview) depend on the detailed imaging error statistics toggle. The toggle is off by default. While it is off, the per-cause error breakdown is not collected, so both columns are always 0 and the Real vs Expected donut always shows 100% real errors. To enable the toggle, contact Relativity Support.

The Password Protected and Type Not Supported columns separate failures that usually need no action from genuine processing errors, which helps triage which errored documents are actionable. Both columns count only documents that were part of the imaging job and errored - they are tallied from the job's population table, so files that are excluded before they reach imaging are not counted:

Password Protected - documents that errored because the file is password-protected and the password is not in the workspace Password Bank. These can become imageable once the password is supplied, so they often need no action beyond adding the password.
Type Not Supported - documents that errored because the imaging engine does not support the file format (for example, audio files or executables). Only a document that the job attempted and that returned a "document type is not supported" error is included; a file that is filtered out before being added to the job does not appear here.

How to read it: Start with Errored Documents Over Time to spot when errors spiked, then use Raw Error Data to find the specific jobs in that window and click a jump-link to investigate a single job in Discover.

Agent Errors

Imaging Errors & Warnings - agent errors, exceptions, and error logs

These three panels are sourced from the imaging agent error logs (agent logs filtered to the imaging agent application and an error or fatal log level) rather than from an imaging OTEL metric. They expose agent-side failures that are not tied to a specific document.

The per-agent breakdowns are grouped by agent. Imaging runs three agents:

Imaging Request Agent - Subscribes to imaging request messages and submits documents for imaging.
Imaging Response Agent - Subscribes to imaging response messages and records the imaging results.
Imaging Manager - Performs background maintenance for imaging: cleans up imaging jobs (including stuck jobs) and unlinked imaging warnings, and checks that an Imaging Response Agent is active.

The panels are:

Agent Errors Over Time - A multi-series line chart of agent error-log volume over time, one line per imaging agent. Hover over a time bucket to see each agent's error-log count for that bucket, sorted descending. Use it to see when agent errors occur and which agent is affected.
Agent Exceptions by Type - A horizontal stacked-bar chart that groups agent errors by exception type (the underlying technical exception class, such as a timeout or lock-lost exception), stacked by agent, with the total at the end of each bar. Use it to see what kind of failure is occurring.
Agent Error Logs - A horizontal stacked-bar chart that groups agent errors by log message (the human-readable message each agent logged), stacked by agent, with the total at the end of each bar. Use it to read the actual error messages behind the exceptions. The chart scrolls vertically when many entries are present.

Agent Exceptions by Type vs Agent Error Logs. Both panels summarize the same agent errors from different angles: Agent Exceptions by Type groups by the technical exception class, while Agent Error Logs groups by the readable log message. Read Agent Exceptions by Type to categorize failures, then Agent Error Logs to see the exact wording.

Explore in Discover: Agent Exceptions by Type and Agent Error Logs both open the underlying agent error logs in Discover, in a new browser tab, using the same time range as the dashboard:

Explore in Discover ↗ (top right of each panel, above the legend) - Opens all agent error logs counted in the panel. The Discover hit count equals the sum of the bars. Error logs that have no exception type (or no log message template) are not shown as bars, so they are excluded.
A bar segment - Opens the logs for that exception type or log message from that agent only.
The total at the end of a bar, or the label on the left - Opens the logs for that exception type or log message from all agents.

The Discover view uses the logs-* data view with the columns needed for investigation (log level, agent name, exception type or message template, message, and stack trace), sorted newest first. The Discover hit count matches the count shown on the bar. Hover over a bar, total, or label to see its tooltip before you click.

Need the full log stream? These three panels show only error- and fatal-level agent logs. To read the complete imaging log stream for deeper investigation, open the [Relativity] Imaging Logs saved search in Discover, available from the Logs, Searches, and Alerts list in the Imaging dashboard navigation.

Screenshot note: The screenshot is illustrative; in some environments, high-volume entries can include telemetry or health-check reporting failures rather than document-imaging failures, so always confirm context in the raw log rows.

Imaging Warnings

Imaging Errors & Warnings - warnings by workspace, type, file type, and over time

Imaging warnings capture non-fatal issues raised during imaging. All warning panels share the same seven warning types, which sum into Total Imaging Warnings:

Cut-Off Text - Text was cut off in the produced image.
Cut-Off Image - An image was cut off in the produced image.
Cut-Off Not Performed - Expected cut-off handling was not applied.
Table Split - A table was split across pages.
Table Split Not Completed - A table split could not be completed.
Malformed RTF Data - The source document contained malformed RTF data.
Encoding Mismatch - A character-encoding mismatch was detected.

The panels are:

Imaging Warnings per Workspace - A table grouped by workspace and host, with a column for each of the seven warning types and a Total Imaging Warnings column. Use it to find which workspaces generate the most warnings.
Warnings by Type - A set of metric tiles, one per warning type, showing the total count of each across the environment (plus an Undefined Imaging Warnings catch-all tile) so the most common warning categories stand out.
Warnings by File Type - A table of Total Imaging Warnings grouped by file type, identifying content types that most often trigger warnings.
Warnings Over Time - A time-bucketed line chart of total warnings. Hovering works the same way as on Errored Documents Over Time.
Raw Warning Data - A row-level table of warning events with Latest Timestamp, Correlation Id, Workspace ID, Host, Process, each of the seven warning-type counts, and Total Imaging Warnings. Identifier cells carry jump-links into a filtered Discover view.

How to read it: Use Warnings by Type and Warnings Over Time to see which warning categories dominate and whether they are rising, Imaging Warnings per Workspace and Warnings by File Type to localize them to specific workspaces or content types, and Raw Warning Data (with its jump-links) to inspect individual warning events.

Use Cases

Use Case	Description
Investigate an error spike	Use Errored Documents Over Time to find when errors spiked, then drill into Raw Error Data for the specific jobs.
Separate real vs expected errors	Use the Password Protected and Type Not Supported columns in Raw Error Data to distinguish actionable failures from failures that usually need no action (password-protected files and unsupported file types).
Diagnose agent-side failures	Use Agent Errors Over Time, Agent Exceptions by Type, and Agent Error Logs to identify which imaging agents are failing and why, then click a bar or Explore in Discover to read the matching log entries and stack traces.
Find the noisiest workspaces	Use Imaging Warnings per Workspace to rank workspaces by warning volume.
Identify warning-prone content	Use Warnings by File Type to find content types that most often trigger warnings.
Track warning trends	Use Warnings Over Time and Warnings by Type to monitor whether warnings are rising and which categories dominate.
Deep-dive a specific job	Use the jump-links in Raw Error Data / Raw Warning Data to open a filtered Discover view scoped to a correlation ID, workspace, or imaging set.

Associated Alerts

No imaging-specific Environment Watch alerts are currently associated with this dashboard. This section will be updated as imaging alerts are published.