Going Crazy Diagnosing ABS-KoSync: Progress Loss, Database Resets, and the ABS Search Engine Nightmare

The Core Problem: Why Your Reading Progress Goes Insane

Let me be straight with you — I’ve been tortured by something called ABS-KoSync recently. If you haven’t used it: it’s a bridge between Audiobookshelf (audiobooks) and KOReader/KoSync (ebooks) that syncs reading progress. Sounds beautiful, right? But when you actually try to diagnose why your progress randomly jumps to 100%, or why the database resets every time you open the app — it’s a nightmare.

Someone on Reddit literally said “I was going crazy trying to diagnose an issue.” That’s not hyperbole. I spent two full nights going from suspecting database write permissions to questioning my life choices. The root cause turned out to be far deeper than I expected.

Here’s the kicker: Google search results for “ABS-KoSync” are polluted with car ABS fault diagnosis content. “VW ABS fault diagnosis leads to hilarious discovery”, “6 symptoms of a bad ABS control module” — these aren’t AI hallucinations. It’s the search engine’s semantic matching confusing ABS (Audiobookshelf Sync) with Anti-lock Braking Systems. If you’re searching for this and seeing a bunch of car repair posts, don’t panic. You’re not alone.

Architecture Deep Dive: How ABS-KoSync Bridge Actually Works

To understand the problem, you need to understand the architecture. The abs-kosync-bridge (by 00jlich) is a Docker container that acts as middleware between Audiobookshelf and the KoSync server.

flowchart LR
    A[KOReader] -->|Pushes progress| B[KoSync Server]
    B -->|Syncs data| C[ABS-KoSync Bridge]
    C -->|Writes progress| D[Audiobookshelf Database]
    D -->|Reads progress| E[Audiobookshelf App]
    E -->|Shows wrong progress| F[User goes crazy]

Here’s the critical part: The KoSync server receives progress updates from KOReader, and the Bridge writes that data into the Audiobookshelf database. If any link in this chain breaks — say KoSync never gets the push, or the Bridge writes data that triggers a database reset — you get the “jumps to 100%” phenomenon.

GitHub Issue #49 has someone explicitly reporting: “Sync ebook to ABS — Since syncing from ABS → KoReader works, the issue is that KoReader isn’t pushing its progress updates to the KoSync server.” In plain English: sync from Audiobookshelf to KOReader works fine, but the reverse direction doesn’t. The problem is KOReader never pushes its progress to KoSync.

Root Cause Analysis: Why Does the Database “Reset”?

This was the part that nearly broke me. The symptom: you manually write to the database, change progress values, but the moment you open the Audiobookshelf app, it reverts. The Reddit user said: “every time you opened the app it reset no matter what.”

I initially suspected Audiobookshelf’s caching mechanism, or database permission issues. But the truth is:

Audiobookshelf reads progress from its own database on startup, but if the Bridge writes an invalid progress field value — like null or something out of range — it falls back to a default (usually 0% or 100%).

What makes it worse: KoSync and Audiobookshelf may define “progress” differently. KoSync uses position (current timestamp in milliseconds), while Audiobookshelf uses progress (a float from 0.0 to 1.0). If the Bridge doesn’t handle the unit conversion properly, it writes a value that looks correct but actually triggers Audiobookshelf’s reset logic.

Diagnosis Steps: From “Going Crazy” to “Fixed”

If you’re hitting this issue, follow this order. Don’t make the same mistakes I did.

Step 1: Verify KOReader Is Actually Pushing Progress

This is the most overlooked step. Everyone jumps to check Bridge logs, but the problem might be at the source.

# Check KoSync config on your KOReader device
# Usually in /mnt/onboard/.adds/koreader/settings.koplugin
# Look for the koreader-kosync-server section
cat /path/to/koreader/settings/koreader-kosync-server.lua | grep -E "url|username|password"

Key: Make sure url points to your KoSync server address (not the Bridge address). A lot of people mix these up during configuration.

Step 2: Check If KoSync Server Is Receiving Data

# Assuming KoSync is running in Docker
docker logs kosync-server --tail 100 | grep -E "progress|position|update"

If there’s no output here, KOReader isn’t pushing. Check network connectivity:

# Ping KoSync server from KOReader device
ping <kosync-server-ip>
# Check if port is open
nc -zv <kosync-server-ip> 8080

Step 3: Check ABS-KoSync Bridge Logs

docker logs abs-kosync-bridge --tail 200

You should see output like:

[INFO] Syncing progress for book "Some Book" to ABS
[INFO] Writing position 1234567 to ABS database

If you see [ERROR] or [WARN] about abnormal progress values, it’s a unit conversion issue.

Step 4: Verify Database Writes Are Correct

Query the Audiobookshelf database directly (using SQLite):

# Enter the Audiobookshelf container
docker exec -it audiobookshelf /bin/sh
# Find the database file, usually at /app/data/absdatabase.sqlite
sqlite3 /app/data/absdatabase.sqlite

In SQLite:

-- View recent progress records
SELECT id, mediaItemId, currentTime, progress FROM mediaProgress ORDER BY updatedAt DESC LIMIT 10;
-- Check for records where progress is NULL or outside 0.0-1.0 range
SELECT * FROM mediaProgress WHERE progress IS NULL OR progress < 0.0 OR progress > 1.0;

If you find progress values of 1.0 but currentTime is far less than total duration, the Bridge’s mapping logic is wrong — it’s using position directly as progress.

Step 5: Fix Bridge Configuration

Edit the abs-kosync-bridge configuration file (usually config.yaml or environment variables):

# Make sure these are correct
kosync:
  url: "http://kosync-server:8080"  # Note: NOT the Bridge's own address
  username: "your-username"
  password: "your-password"

audiobookshelf:
  url: "http://audiobookshelf:13378"
  apiKey: "your-api-key"

# Critical: progress mapping configuration
sync:
  progressMapping: "position_to_percentage"  # Make sure this mode is used
  fallbackOnError: false  # Don't fall back to default values

If the problem persists, try manually fixing records in the database:

-- Fix wrong progress values
UPDATE mediaProgress 
SET progress = CAST(currentTime AS REAL) / 
    (SELECT duration FROM mediaMetadata WHERE mediaMetadata.id = mediaProgress.mediaItemId)
WHERE progress = 1.0 AND currentTime > 0;

Performance & Security: What You Need to Know

The problems with this setup go beyond sync failures.

Performance: Each sync requires four network hops: KOReader → KoSync → Bridge → ABS. If your KoSync server is overseas, or your Audiobookshelf instance is under load, sync latency can hit tens of seconds. This isn’t real-time sync — it’s “sync when it feels like it.”

Security: The Bridge needs your Audiobookshelf API Key — meaning it has full read/write access to your library. If the Bridge container gets compromised, an attacker can delete all your progress records. I’d recommend:

• Create a dedicated Audiobookshelf user for the Bridge with permissions limited to mediaProgress operations
• Use Docker network isolation — don’t expose the Bridge port to the public internet

Data Consistency: This is the most annoying part. If the Bridge crashes mid-write, the database can be left in an inconsistent state. There’s currently no transaction protection mechanism.

Alternatives: You’re Not Stuck With This

If you can’t get ABS-KoSync Bridge working, or if it’s driving you up the wall like it did me, consider these alternatives:

Community Insights: You’re Not Alone

Discussion on r/audiobookshelf and GitHub around this issue is active. In GitHub Issue #49, maintainer cporcellijr explicitly states “the issue is that KoReader isn’t pushing its progress updates to the KoSync server” — currently the most authoritative official answer.

But here’s my take: that explanation isn’t good enough. Why isn’t KOReader pushing? Could be API compatibility issues in certain KoSync versions, or KOReader’s overly conservative network retry strategy. In my testing, KOReader silently drops push requests under weak network conditions — no retry, no error message. That’s a ticking time bomb.

FAQ

Q: Does ABS-KoSync have anything to do with car ABS systems? A: Absolutely nothing. Google’s semantic matching incorrectly confuses ABS (Audiobookshelf Sync) with Anti-lock Braking Systems. If you’re seeing car repair content while searching for this, ignore it.

Q: Why does my progress jump to 100%? A: Usually because the ABS-KoSync Bridge writes an invalid progress value (e.g., outside the 0.0-1.0 range), causing Audiobookshelf to fall back to defaults. Check your database using Step 4 in this article.

Q: Sync from ABS to KOReader works, but not the reverse. What do I do? A: This is the known issue described in GitHub Issue #49. Check KOReader’s KoSync configuration to ensure it points to the correct KoSync server address, and verify KOReader is actually pushing progress (check KoSync server logs).

Q: Does ABS-KoSync Bridge need to be exposed to the public internet? A: Absolutely not. The Bridge only needs internal network access to Audiobookshelf and the KoSync server. Use Docker network isolation and don’t map ports to the host.

Q: How do I permanently fix the database reset issue? A: There’s no official fix yet. I recommend: 1) Use the SQL fix command from this article to clean up invalid records; 2) Set fallbackOnError: false in Bridge config; 3) Regularly back up your Audiobookshelf database.

References & Community Resources

• GitHub Issue #49: Sync ebook to ABS — The core community discussion thread
• ABS-KoSync Bridge Docker Image — Official Docker image
• Reddit r/audiobookshelf — Primary source of community feedback