> For the complete documentation index, see [llms.txt](https://docs.upriverdata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.upriverdata.com/product-usage/data-assets/data-source/troubleshooting-monitoring-configuration.md).

# Troubleshooting Monitoring Configuration

Use this page when Upriver behavior looks wrong — too many alerts, missed issues, connection failures, or monitors that do not match how your data actually updates — and you need to decide whether a **configuration change** is the right fix.

This page is written for both people and agents: match a symptom, verify causes, then apply the **smallest safe correction**. Prefer diagnosis over guesswork.

{% hint style="info" %}
Not every bad alert is a misconfiguration. Real data regressions, pipeline bugs, and expected business changes should not be “fixed” by weakening monitoring.
{% endhint %}

## How to use this page

### For users

1. Find the symptom that best matches what you see.
2. Work through **Likely causes** and **What to check** before changing settings.
3. Apply only the correction that matches the evidence.
4. If you still cannot tell, ask one focused follow-up question (or escalate to a teammate / Upriver support) rather than changing several knobs at once.

### For agents

1. Match the user’s description and evidence to exactly one playbook when possible.
2. Prefer the **smallest targeted** configuration change that the playbook justifies.
3. Do **not** invent thresholds, permissions, or settings that are not present in the current configuration or the user’s statement.
4. If evidence is insufficient, ask **one** focused follow-up question. If still uncertain, recommend human review — do not force a configuration proposal.
5. Proposed monitoring changes must remain **review-only** until the user approves them.
6. Treat this documentation as the customer-facing source of truth for terminology and common cases. Link users to related product pages when deeper setup detail is needed.

### Related documentation

* [Data Source Configuration](/product-usage/data-assets/data-source/data-source-configuration.md)
* [Data Source Fields](/product-usage/data-assets/data-source/data-source-fields.md)
* [Incident Types](/product-usage/incidents/incident-types.md)
* [Managing Incidents](/product-usage/incidents/managing-incidents.md)
* [Metadata Monitoring](/monitoring/metadata-monitoring.md)
* [Field Behavior Monitoring](/monitoring/field-behavior-monitoring.md)

***

## Symptom index

1. [Too many noisy or false-positive incidents](#1-too-many-noisy-or-false-positive-incidents)
2. [A real issue was not detected or was hidden](#2-a-real-issue-was-not-detected-or-was-hidden)
3. [Freshness or staleness alerts look wrong](#3-freshness-or-staleness-alerts-look-wrong)
4. [Volume or row-count alerts look wrong](#4-volume-or-row-count-alerts-look-wrong)
5. [Connection or permission failures](#5-connection-or-permission-failures)
6. [Monitor stuck in Learning or never feels stable](#6-monitor-stuck-in-learning-or-never-feels-stable)
7. [Monitor shows Stale or Paused unexpectedly](#7-monitor-shows-stale-or-paused-unexpectedly)
8. [Wrong fields are monitored](#8-wrong-fields-are-monitored)
9. [User expectations firing incorrectly](#9-user-expectations-firing-incorrectly)
10. [Schedule runs at the wrong time or misses the window](#10-schedule-runs-at-the-wrong-time-or-misses-the-window)
11. [Onboarding is incomplete](#11-onboarding-is-incomplete)
12. [Wrong nested vs multiple pivot layout](#12-wrong-nested-vs-multiple-pivot-layout)

***

## 1. Too many noisy or false-positive incidents

### Symptom

Incidents fire often for values or patterns that the team considers normal, or the same field keeps alerting without actionable root cause.

### Likely causes

1. Default or field-level **sensitivity** is too high for a noisy source.
2. A field that should not be monitored is still in scope.
3. An **incident type** that is not useful for this source is still enabled.
4. Automatic expectations are too tight for natural variation.
5. A legitimate data shift was triaged as **Misdetection** (or left unresolved) instead of **Expected Change**, so the baseline never caught up.

### What to check

* Data source status (`Learning` vs `Running`) — tighten carefully while learning.
* Default sensitivity and any field / metric sensitivity overrides.
* Whether the noisy field is business-critical or can be excluded.
* Incident type history for that field or data source.
* Whether the change is a real new normal (schema rollouts, new enums, volume growth).

### How to correct

* Lower sensitivity for the data source, or only for the noisy field / metric.
* Exclude a non-critical noisy field from monitoring (field remains type-checked only).
* Exclude a specific incident type for that field or data source when the type is not actionable.
* Loosen or clear an overly strict **user expectation**.
* For a legitimate new normal: mark matching incidents as **Expected Change** and, when needed, add or update a user expectation so future runs reflect the new baseline.
* Prefer the narrowest lever: field/metric first, then incident type, then data-source defaults.

### When not to change config

* The values really are anomalous and need pipeline or data fixes.
* You are still in early **Learning** and the baseline has not stabilized.
* Using **Misdetection** only to silence a real-but-inconvenient change — that corrupts the baseline; use **Expected Change** instead.

***

## 2. A real issue was not detected or was hidden

### Symptom

Users report a data problem that Upriver did not surface, or an incident existed but was hidden / auto-suppressed / never raised.

### Likely causes

1. The data source is **Paused**.
2. Sensitivity is too low (data source, field, or metric).
3. The field or incident type is excluded.
4. User expectations are too wide, so the value is treated as expected.
5. The schedule or run window did not cover the time of the issue.

### What to check

* Whether the data source is **Paused**.
* Default sensitivity and field / metric overrides.
* Field scope and incident-type exclusions.
* User expectations on the relevant field.
* Schedule / contract update interval vs when the issue occurred. See [Data Source Configuration](broken://pages/490bb35bd27634011cb7ed63e16ae64a89d13a44).

### How to correct

* Re-enable raising incidents or resume a paused monitor.
* Raise sensitivity only as far as needed (prefer field/metric over global).
* Re-include an excluded field or incident type.
* Tighten a user expectation when there is a clear business rule.
* Align schedule or cadence so runs cover the relevant window.

### When not to change config

* No monitor covers the table yet — onboard monitoring instead of tuning an unrelated source.
* The issue is outside what Upriver monitors (for example, a pure code path with no data signal).
* Evidence is conflicting — ask one focused question, then escalate to human review.

***

## 3. Freshness or staleness alerts look wrong

### Symptom

Freshness / staleness incidents fire when data is on time, or a source never alerts when updates stop.

### Likely causes

1. **Staleness threshold** does not match the real update cadence.
2. Schedule / run delay is misaligned with when data lands.
3. Wrong **timestamp column** (for example `updated_at` vs event time).
4. Custom freshness expectation is too strict or too loose.
5. Upstream pipeline idle time is real — not a monitoring misconfig.

### What to check

* Expected update cadence (hourly, daily, weekly, bursty).
* Staleness threshold relative to that cadence.
* Monitor schedule, update time, and run delay (UTC).
* Timestamp column semantics on the data source.
* Custom freshness expectation on the freshness chart, if set. See also [Metadata Monitoring](broken://pages/e863a04b5e2ce5b3349e7149611a5829827e8748).

### How to correct

* Raise or lower the staleness threshold to a small multiple of the expected update interval.
* Fix schedule / run delay so extraction runs after data is available.
* Switch to the timestamp column that reflects when rows arrive.
* Edit or clear a custom freshness expectation that fights reality.
* Prefer adjusting staleness / schedule over silencing every freshness incident.

### When not to change config

* The pipeline truly stopped or delayed — fix the pipeline, then keep monitoring.
* The source is intentionally batch-idle for long periods and should be **Manual Trigger** or paused, not “always fresh.”

***

## 4. Volume or row-count alerts look wrong

### Symptom

Volume incidents fire on normal load swings, or large volume drops / spikes are missed.

### Likely causes

1. Automatic volume baseline does not match bursty or seasonal traffic.
2. Custom min/max volume expectation is wrong.
3. Sampling or “only analyze updated data” changes what volume looks like.
4. Low-row-count behavior / related settings suppress or amplify alerts.
5. Schedule compares unequal windows (partial day vs full day).

### What to check

* Volume chart history and whether swings are expected.
* Custom volume expectations on the volume chart.
* Sampling rate / dynamic sampling.
* Schedule alignment with partition or batch boundaries.
* Whether duplicates or missing batches are real pipeline issues. See also [Metadata Monitoring](broken://pages/e863a04b5e2ce5b3349e7149611a5829827e8748).

### How to correct

* Set or adjust a custom volume expectation when business bounds are known.
* Align schedule and extraction window with how batches land.
* Adjust sampling only when it materially distorts the profile (do not use sampling as the primary mute).
* For globally noisy low-volume tables, review low-row-count related monitor settings together with sensitivity — keep changes minimal.

### When not to change config

* Sudden zero rows or duplicate spikes that match a broken job — fix the pipeline.
* One-off backfills: triage with **Expected Change** when appropriate, rather than permanently widening bounds unless the new volume is lasting.

***

## 5. Connection or permission failures

### Symptom

Data source setup, runs, or profiling fail with authentication, authorization, missing object, or network errors.

### Likely causes

1. Integration credentials expired or rotated.
2. Warehouse / cloud role lacks required permissions.
3. Wrong database, schema, table, bucket, topic, or region.
4. Network path (PrivateLink, firewall, IP allowlist) blocks Upriver.
5. Object was renamed or deleted upstream.

### What to check

* Integration health and last successful connection.
* Exact connection identifiers (project/dataset/table, db/schema/table, bucket/prefix, stream/topic).
* Role / IAM grants documented for that connector.
* Recent infra or credential rotations. Use the connector guides under Integrations (for example [Snowflake](broken://pages/ccae4971986652cb1de20d80a0d79a35b2b07c28), [BigQuery Permissions](broken://pages/9f492970f8dc2a5f0684b3557f46ba6f0bc85f16), [Databricks](broken://pages/c251ffbcf91c9888380adcbe11ae9c117a9bf932), [Network](broken://pages/9c738c2d3b12531a433d8e3633a12293a900b0ce)).

### How to correct

* Refresh credentials on the integration.
* Grant the missing permissions to the Upriver role / service account.
* Fix connection identifiers on the data source.
* Update network allowlists or private connectivity as required by your environment.
* Re-point or recreate the data source if the upstream object moved.

### When not to change config

* Do not “fix” connection errors by muting incidents or lowering sensitivity — the monitor cannot observe data it cannot read.
* Do not invent permission grants; follow the connector’s documented permission set.

***

## 6. Monitor stuck in Learning or never feels stable

### Symptom

The data source stays in **Learning**, or every small variation creates incidents before a trustworthy baseline exists.

### Likely causes

1. Too few successful runs to form a baseline.
2. Cadence is too infrequent relative to how fast the team expects stability.
3. Highly volatile data with aggressive sensitivity / expectations applied too early.
4. Runs failing intermittently, so learning never completes cleanly.

### What to check

* Data source lifecycle status and recent run success.
* Schedule / contract update interval.
* Whether sensitivity or user expectations were tightened during Learning.
* Connection health if runs fail.

### How to correct

* Allow additional successful runs before aggressive tuning.
* Align schedule with real update frequency so learning samples representative windows.
* Keep sensitivity at a conservative default until **Running**.
* Fix failing runs (connection / permissions / query errors) before judging the baseline.

### When not to change config

* Do not pile on many field expectations or high sensitivity during Learning.
* Do not mark everything as Misdetection just to “finish learning” — that trains the wrong normal.

***

## 7. Monitor shows Stale or Paused unexpectedly

### Symptom

A data source flips to **Stale**, or monitoring appears stopped (**Paused**) when the team expected continuous coverage.

### Likely causes

1. Staleness threshold shorter than real idle gaps.
2. Upstream data truly stopped updating.
3. Someone paused the monitor or disabled raising incidents.
4. Schedule is Manual Trigger and nobody ran it.
5. Connection failures make the source look inactive.

### What to check

* Status: `Stale` vs `Paused` vs muted incidents.
* Staleness threshold vs real cadence.
* Schedule mode (scheduled vs manual).
* Recent successful extraction / contract runs.
* Whether the upstream pipeline is idle on purpose.

### How to correct

* Raise staleness threshold when idle gaps are normal.
* Resume monitoring / re-enable raising incidents if paused intentionally or by mistake.
* Switch from Manual Trigger to a schedule when continuous coverage is required.
* Fix connection or pipeline issues when the source is incorrectly idle.

### When not to change config

* Long intentional freezes (migrations, seasonal tables) may warrant pause or manual trigger rather than ever-looser staleness.
* Do not hide staleness if the business still needs to know when data stopped.

***

## 8. Wrong fields are monitored

### Symptom

Incidents concentrate on irrelevant columns, or important columns never produce field-level signals.

### Likely causes

1. Noisy high-cardinality or free-text fields left in scope.
2. Important fields excluded from monitoring.
3. Pivot fields chosen poorly (too many values, or wrong dimension).
4. Filter / cardinality threshold classifies fields incorrectly.
5. Nested / semi-structured fields need flatten or schema attention.

### What to check

* Fields tab: which fields are excluded vs monitored.
* Incident concentration by field.
* Pivot configuration and cardinality of pivot values.
* Filters and cardinality threshold on the data source. See [Data Source Fields](broken://pages/5181ddca1f443232d1affde371fda02c601d839c) and [Pivot Fields](broken://pages/a4a05b21b09000a05aceaaf8ed5f4345e5875b06).

### How to correct

* Exclude fields that should not alert (IDs, free text, debug columns).
* Re-include business-critical fields that were hidden.
* Limit pivots to low-cardinality business dimensions; avoid using primary keys as pivots.
* Adjust filter or cardinality threshold when classification is clearly wrong.
* Prefer excluding a field over disabling the whole monitor.

### When not to change config

* A critical field is noisy because the data is wrong — fix the data, keep the field monitored.
* Do not create large pivot explosions “to see everything”; keep pivot sets small.
* If the pivot fields are correct but their hierarchy is wrong, use [Wrong nested vs multiple pivot layout](#12-wrong-nested-vs-multiple-pivot-layout) instead of excluding fields.

***

## 9. User expectations firing incorrectly

### Symptom

**Unmet User Field Expectation** or **Unmet User Metadata Expectation** incidents fire for values the business accepts, or hard business rules never alert.

### Likely causes

1. Allowed values / numeric bounds are outdated after a product change.
2. Completeness or uniqueness thresholds do not match reality.
3. Volume / freshness user expectations conflict with automatic monitors.
4. Triage status taught the wrong lesson (**Misdetection** vs **Expected Change**).

### What to check

* The exact user expectation on the field or metadata chart.
* Recent legitimate schema / enum / range changes.
* Incident status history for those expectation incidents. See [Data Source Fields](broken://pages/5181ddca1f443232d1affde371fda02c601d839c) and [Incident Types](broken://pages/7f636003ff0bb3483cb2903a41b39e9e78a9c1d4).

### How to correct

* Update allowed values or bounds to the new business rule.
* Clear an expectation that should no longer be enforced.
* Add a tighter expectation only when the rule is explicit and owned by the business.
* Triage legitimate shifts as **Expected Change**; reserve **Misdetection** for alerts that were never valid.

### When not to change config

* Do not invent business thresholds without user confirmation.
* Do not remove an expectation solely because it is inconvenient if the rule is still required.

***

## 10. Schedule runs at the wrong time or misses the window

### Symptom

Runs finish before data lands, repeatedly scan empty / partial windows, or never catch issues that self-correct within the day.

### Likely causes

1. Update time (UTC) does not match when batches arrive.
2. **Run delay** is too small or too large.
3. Contract update interval is coarser than the issue lifetime.
4. Dynamic schedule does not match a strict SLA window.
5. Manual trigger used where a fixed schedule is required.

### What to check

* Monitor scheduling mode: Update Time, Dynamic Update, or Manual Trigger.
* Hour / minute in **UTC** and run delay.
* Upstream job completion time vs Upriver run time.
* Whether the issue appears and disappears between runs.
* Recent freshness across runs — consistently high freshness near the expected update interval often means the monitor ran just before the new batch landed. See [Data Source Configuration](broken://pages/490bb35bd27634011cb7ed63e16ae64a89d13a44).

### How to correct

* Set update time and run delay so extraction starts after data is ready.
* If incidents appear one cycle late and freshness shows the previous batch was still the newest data at run time, move **Update Time** later so the monitor runs after the batch normally completes. Add a modest buffer for ordinary pipeline variation. Keep the existing cadence unless separate evidence shows it is wrong.
* Shorten the contract update interval when short-lived issues must be caught.
* Switch to a fixed update time when dynamic timing drifts from the SLA.
* Use Manual Trigger only when human-driven runs are intentional.

### When not to change config

* If data arrival time is unstable because the pipeline is failing, fix the pipeline first.
* Do not assume local timezone — schedules are configured in UTC.
* Do not change sensitivity or freshness thresholds when the evidence points to a missed schedule window.

***

## 11. Onboarding is incomplete

### Symptom

An asset is discovered or a data source exists, but monitoring is not useful yet: missing timestamp, odd sampling, no owners, wrong object, or never runs.

### Likely causes

1. Monitor never created for a discovered asset, or still **Initializing**.
2. Wrong or missing **timestamp column**.
3. Primary keys / sampling / format not set for the asset type.
4. Integration connected, but the wrong table / topic / prefix was selected.
5. Owners and notifications not configured, so issues are unseen even when detected.

### What to check

* Whether a data source monitor exists for the asset.
* Connection identifiers and data format (for files).
* Timestamp column, primary keys, sampling, schedule, sensitivity, staleness.
* Owners, Slack / webhook notification settings. See [Data Source Configuration](broken://pages/490bb35bd27634011cb7ed63e16ae64a89d13a44).

### How to correct

* Create or finish monitor setup for the discovered asset.
* Choose the timestamp that reflects arrival / event time; omit only when full scans are intended.
* Set primary keys for uniqueness where they are known.
* Pick sampling appropriate to volume (full for small tables; lower or dynamic for large).
* Assign owners and notification channels so detections reach the right people.
* Trigger a manual run after setup to validate.

### When not to change config

* If the integration is not connected, connect the integration first — do not invent a monitor for an undiscovered asset.
* If multiple tables could match the user’s request, confirm the target before configuring.

***

## 12. Wrong nested vs multiple pivot layout

### Symptom

The monitor has more than one pivot field, but its derived data sources do not match how the team wants to analyze the data. You may see too many nested combinations, independent groupings where you expected drill-down, or a hierarchy in the wrong order.

This is a pivot **layout** problem. If the selected columns themselves are wrong, see [Wrong fields are monitored](#8-wrong-fields-are-monitored).

### Likely causes

1. **Nested Pivots** were selected when each dimension should be monitored independently.
2. **Multiple Pivots** were selected when the team needs intersections between dimensions.
3. Nested pivots generated too many combinations because the selected fields have too many distinct values.
4. The pivot order is wrong for the intended hierarchy.

### What to check

* Whether the monitor uses **Nested Pivots** or **Multiple Pivots**.
* The business question:
  * “Within each X, how does Y behave?” indicates nested pivots.
  * “How does the data behave by X and separately by Y?” indicates multiple pivots.
* Whether the derived data sources form the expected structure:
  * Nested pivots split the parent by the first field, then split each child by the next field.
  * Multiple pivots apply every field directly to the parent as independent, same-level groupings.
* The cardinality of every pivot field. With nested pivots, the number of combinations can grow quickly.
* The order of fields when using nested pivots. See [Pivot Fields](/product-usage/data-assets/pivot-fields.md).

### How to correct

* Choose **Nested Pivots** for layered drill-down and intersections, such as `region` followed by `status` within each region.
* Choose **Multiple Pivots** for independent comparisons, such as monitoring by `region` and separately by `source`.
* Reorder nested fields so the broadest business grouping is first and the desired drill-down is second.
* Reduce or replace high-cardinality pivot fields when the hierarchy creates too many derived data sources.
* Before switching an existing monitor between nested and multiple pivots, confirm the intended structure: changing the layout recreates its derived data sources.

### When not to change config

* Do not switch layouts merely to silence noisy incidents from one unsuitable pivot field. Remove or replace that field instead.
* Do not nest every categorical field “to see everything”; keep pivots limited to useful business dimensions.
* With only one pivot field, nested versus multiple does not change the resulting layout.

***

## When a configuration change is not the answer

Stop proposing monitoring edits and ask one focused question or escalate when:

* Evidence points to a **pipeline bug**, warehouse outage, or bad deploy rather than monitor settings.
* The case is a **real data quality regression** that should stay visible.
* The needed fix is outside editable monitoring settings (for example, missing product signal or unsupported connector behavior).
* Documentation does not cover the case and inventing a setting would be unsafe.
* Multiple playbooks fit equally well and one clarifying answer would decide between them.

{% hint style="success" %}
**Rule of thumb:** change the smallest setting that matches verified evidence. If you cannot explain why the new value is better than the current one, do not change it yet.
{% endhint %}