elastic / elastic/docs-content

[Internal]: Add Synthetics troubleshooting section: `observer.geo.name` mapping conflict after upgrade

Open
#7,547 2 comments 0 reactions 1 assignee Claimed by @gbocchini View on GitHub
Team:SKI
Dominant language
No language data
Stars
47
Forks
261
Avg merge
3d 21h
Merged PRs (30d)
141

Description

### Description

## Problem

When upgrading from 9.3.3 to 9.4.3 (or any version picking up elastic/integrations#19757), Synthetics monitors may enter a persistent "pending" state. The root cause is a mapping conflict:

```
mapper [observer.geo.name] cannot be changed from type [wildcard] to [keyword]
```

The change in integrations#19757 updated `observer.geo.name` from `wildcard` → `keyword`. Existing indices created before the upgrade retain the old mapping. Fleet cannot update the mapping in-place, so affected data streams reject writes until the index is rolled over.

## Expected behavior

- **Active monitors** (writing data regularly): Fleet triggers a lazy rollover on the next write. Monitors self-heal on their next scheduled run — no manual action needed.
- **Infrequent or paused monitors**: No recent writes means no automatic rollover. These monitors remain in "pending" indefinitely until a manual rollover is performed.

## Mitigation

For monitors that do not self-heal, manually roll over the affected data streams:

```
POST /synthetics-*/_rollover
```

After rollover, monitors recover on their next scheduled run. There is no checkpoint or state loss for Synthetics — unlike log-based inputs, Synthetics monitors do not maintain event position state.

## What to add to docs

A troubleshooting entry under the Synthetics section (suggested location: *Troubleshoot Synthetics > Monitors stuck in pending state*) covering:

1. **Symptoms:** Monitors show "pending" after upgrading; no results indexed; no errors visible in the monitor UI
2. **Root cause:** `observer.geo.name` mapping conflict from the integrations upgrade
3. **Resolution:** Active monitors self-heal; idle monitors require `POST /synthetics-*/_rollover`
4. **Scope:** Applies to all Synthetics monitor types (lightweight and browser)

---

Feel free to adjust the suggested docs location — I don't know the exact page structure of the Synthetics docs, so you may want to point it at a more specific subsection.

### Resources

## References

- elastic/integrations#19757 — the change that introduced the mapping type update
- [Slack thread](https://elastic.slack.com/archives/CE4MRBU48/p1784288538645459)

### What Elastic Stack release is this request related to?

`9.4.3`

### Point of contact.

**Main contact:** @mgiota

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.