# How to Debug Sync Issues and Missing Sessions in AgentsView

> Troubleshoot AgentsView sync issues and missing sessions. Enable debug logging, force a sync, and trace the pipeline from watcher to engine to DB to pinpoint data dropouts.

- Repository: [Kenn Software/agentsview](https://github.com/kenn-io/agentsview)
- Tags: how-to-guide
- Published: 2026-06-12

---

**TLDR:** Enable debug logging with `AGENTSVIEW_LOG_LEVEL=debug`, force a full sync using `agentsview sync`, and trace the pipeline from [`internal/sync/watcher.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/watcher.go) through [`internal/sync/engine.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/engine.go) to [`internal/db/sessions.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/sessions.go) to identify where sessions drop out of the synchronization flow.

AgentsView is an open-source tool from **kenn-io/agentsview** that maintains a synchronized view of AI-agent sessions by watching filesystem changes and persisting them to a local SQLite or PostgreSQL database. When sessions fail to appear or updates seem stalled, the issue typically resides in one of four layers: the file watcher, the sync engine, the parser, or the database writer. Understanding how to inspect each layer allows you to diagnose missing data without guesswork.

## Understanding the AgentsView Sync Pipeline

AgentsView follows a pipeline architecture. The **file watcher** ([`internal/sync/watcher.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/watcher.go)) monitors the data directory for changes, feeding events into the **sync engine** ([`internal/sync/engine.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/engine.go)). The engine orchestrates **parsers** ([`internal/parser/zed.go`](https://github.com/kenn-io/agentsview/blob/main/internal/parser/zed.go), [`internal/parser/workbuddy.go`](https://github.com/kenn-io/agentsview/blob/main/internal/parser/workbuddy.go), etc.) to extract session data, which is then written to the database via [`internal/db/sessions.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/sessions.go). Finally, the **server API** ([`internal/server/sessions.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/sessions.go)) surfaces this data to the UI. If any stage fails, sessions appear missing.

## Enable Debug Logging to Expose Runtime Behavior

Before investigating specific components, enable verbose logging to capture the internal state of the sync process.

### Set the Log Level Environment Variable

Run AgentsView with the `AGENTSVIEW_LOG_LEVEL` environment variable set to `debug`. This outputs granular logs from the watcher, engine, and database layers, initialized in [`cmd/agentsview/main.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/main.go).

```bash
export AGENTSVIEW_LOG_LEVEL=debug
agentsview serve

```

### Identify Key Log Patterns

Search the logs for these specific markers:

- `watcher: new file` – Confirms the filesystem watcher detected a change.
- `starting sync` / `finished sync` – Emitted by [`internal/sync/engine.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/engine.go) to mark sync boundaries.
- `parser:` – Indicates activity in `internal/parser/`; errors here mean a file was seen but could not be processed.
- `SQLITE_BUSY` or `database is locked` – Signals contention in [`internal/db/sessions.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/sessions.go).

## Verify the File Watcher is Active

If incremental updates fail while manual imports work, the watcher may be inactive or misconfigured.

Check that `AGENTSVIEW_DATA_DIR` points to the correct path containing your agent subdirectories. If the directory is correct but no `watcher:` logs appear, your operating system may have hit its file notification limit. On Linux, increase the inotify watch limit:

```bash
sudo sysctl fs.inotify.max_user_watches=524288

```

## Force a Full Sync to Bypass Incremental Failures

When the watcher works but sessions remain missing, force a complete re-scan. This bypasses incremental event handling and re-processes every file.

```bash
agentsview sync

```

For PostgreSQL backends, use:

```bash
agentsview pg sync

```

After completion, check the `sync_progress` metrics written by [`internal/sync/progress.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/progress.go). Validate that `total_files` matches the actual file count in your data directory and that `failed_files` is zero.

```bash
find $AGENTSVIEW_DATA_DIR -type f | wc -l

```

## Inspect Parser Execution for Silent Failures

If the sync runs but specific sessions are absent, the parser may be failing. Look for `parser:` error lines in the debug log. To isolate a specific file, run the parser manually:

```bash
go run ./cmd/agentsview --parse $AGENTSVIEW_DATA_DIR/zed/problematic-session.json

```

This outputs the exact error preventing the session from being structured for the database.

## Query the Database Directly

Confirm that successfully parsed data actually reached the database. Open the default SQLite database located at `$HOME/.agentsview/agentsview.db`:

```bash
sqlite3 $HOME/.agentsview/agentsview.db

```

Verify recent sessions exist:

```sql
SELECT id, agent, created_at 
FROM sessions 
ORDER BY created_at DESC 
LIMIT 10;

```

If rows are missing despite successful parser logs, inspect [`internal/db/sessions.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/sessions.go) for transaction rollback conditions or constraint violations.

## Resolve Database Lock Contention

High-frequency updates can trigger `SQLITE_BUSY` errors visible in the logs. This occurs when the sync engine attempts concurrent writes to [`internal/db/sessions.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/sessions.go). Solutions include:

- Increasing the SQLite connection pool size if configurable.
- Switching to the PostgreSQL backend for higher concurrency: `agentsview pg serve`.

## Validate the Server API and UI Layer

If the database contains sessions but the UI shows none, the issue lies in [`internal/server/sessions.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/sessions.go). Query the API directly to confirm:

```bash
curl -s http://localhost:8080/api/sessions?limit=5 | jq .

```

An empty response here indicates filtering logic (such as hidden agents) or a data retrieval bug in the server layer, rather than a sync failure.

## Summary

- Enable `AGENTSVIEW_LOG_LEVEL=debug` to expose watcher events, engine boundaries, and database errors.
- Inspect [`internal/sync/watcher.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/watcher.go) logs and system inotify limits if incremental updates stall.
- Force a full sync with `agentsview sync` to isolate incremental watcher issues.
- Check [`internal/sync/progress.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/progress.go) metrics (`total_files`, `processed_files`, `failed_files`) against actual filesystem counts.
- Run parsers manually using `--parse` to isolate file-specific errors.
- Query `agentsview.db` directly to verify [`internal/db/sessions.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/sessions.go) persistence.
- Switch to PostgreSQL (`agentsview pg serve`) if `SQLITE_BUSY` errors indicate lock contention.
- Use `curl` against `/api/sessions` to determine if the problem is in [`internal/server/sessions.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/sessions.go) rather than the sync pipeline.

## Frequently Asked Questions

### Why are my sessions missing after a file change?

Missing sessions after a file change usually indicate the file watcher in [`internal/sync/watcher.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/watcher.go) missed the event or the parser rejected the file. Check debug logs for `watcher:` entries to confirm detection, then run the parser manually on the file to catch validation errors.

### How do I fix "database is locked" errors during sync?

This error originates from [`internal/db/sessions.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/sessions.go) when the SQLite database receives concurrent write requests. You can reduce sync frequency or migrate to PostgreSQL by running `agentsview pg serve`, which handles concurrency better than the default SQLite backend.

### What is the difference between incremental and full sync in AgentsView?

Incremental sync relies on the file watcher ([`internal/sync/watcher.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/watcher.go)) to react to real-time filesystem events. Full sync, triggered by `agentsview sync`, scans the entire `AGENTSVIEW_DATA_DIR` and re-processes every file regardless of previous state, which is useful for recovering from missed events or corruption.

### How can I verify if the file watcher is detecting my new session files?

Add a new file to your data directory and look for `watcher: new file` entries in the logs when running with `AGENTSVIEW_LOG_LEVEL=debug`. If no entry appears within seconds, verify the `AGENTSVIEW_DATA_DIR` configuration and check your OS file notification limits (e.g., `fs.inotify.max_user_watches` on Linux).