Troubleshooting and FAQ

Troubleshooting and FAQ

Why do I see only 100 messages with All Messages selected?

The current implementation requests history in pages of up to 100. It should continue after the first page until Telegram returns no new message IDs. If the summary remains at exactly 100:

1. confirm that the chat truly has older accessible messages;
2. press Refresh to invalidate a stale completed snapshot;
3. keep the app connected while the next page loads;
4. run the current build, not an older binary;
5. inspect the scan error and repository verification output.

Regression tests cover approximate first-page totals, short nonempty pages, and the boundary message.

Why does All Messages take so long?

It is exhaustive pagination, not a larger fixed limit. Duration depends on chat size, network latency, media density, Telegram service conditions, and rate limits. Use 25–500 for quick browsing.

Why did a FLAC music item not appear?

The mapper supports music/audio as well as generic documents. Refresh the correct chat and confirm the selected history range reaches the message. If the message is older than the range, increase the range or use All Messages.

Why is a filename unnamed-audio-…?

Telegram did not provide a usable original or file-representation filename. Unspool uses a neutral deterministic fallback and does not invent a song name from artist or title metadata.

Why is a file marked already downloaded?

The local guard found a completed history record with the same Telegram file ID. Use Download Again if intentional. The new attempt still goes through conflict preflight.

Why was an existing file skipped?

Skip is the default conflict action. Start the batch again and explicitly choose Replace or Save a Copy for that destination.

Why can Unspool no longer use my folder?

The security-scoped bookmark can become stale after a folder is renamed, moved, deleted, denied, or placed on an unavailable volume. Choose the folder again in Settings.

Why does pause not stop every active file immediately?

Pause stops new scheduling. Already running files finish or fail, after which the state becomes fully paused. Use Cancel for active TDLib cancellation.

What does Resume Download Session do?

It restores the saved batch inputs and conflict choices, then performs a new preflight. It does not assume disk capacity or conflicts are unchanged.

Where are credentials stored?

API ID and API hash are in macOS Keychain. Login codes and two-step passwords are kept in memory for the active authorization step and are not deliberately written to Unspool's JSON stores.

Does Sign Out delete my downloads?

No. It removes saved API credentials after TDLib logout succeeds. Downloaded files and other local app data remain.

Why will the project not build?

Run:

xcodegen generate --spec project.yml
swiftformat Unspool UnspoolTests UnspoolUITests --lint
swiftlint lint --config .swiftlint.yml
xcodebuild -project Unspool.xcodeproj -scheme Unspool test
xcodebuild -project Unspool.xcodeproj -scheme Unspool build-for-testing

Common causes are a missing full Xcode, missing Homebrew tools, a missing TDLib artifact, or a generated artifact that does not match committed pins. Use Building and Dependencies and the repository troubleshooting guide.

Is there a downloadable app?

Not yet. The current repository is a source-only development build without signing or notarization.