Skip to content

How to debug

Jump to bottom
Bobby Comet edited this page Jun 18, 2026 · 5 revisions

Appify 2.1.0: Complete Guide to Debugging, Logging, Backups, and Reporting Issues

Discord Community: https://discord.gg/7fEt5W7DPh
GitHub: https://github.com/bobbycomet/Appify

Table of Contents

  1. Logging
  2. Debugging
  3. Backing Up & Restoring Profiles
  4. Reporting Issues on Discord

Logging

Appify 2.1.0 uses Python's standard logging module at the DEBUG level, meaning every significant action — browser detection, profile writes, launch commands, update checks, extension filtering — is recorded.

Log File Location

~/.pwa_manager/launch.log

The log directory is created automatically on the first run if it does not exist. The file is UTF-8 encoded and appended across sessions, so you can always scroll back through previous runs.

Log Format

Each line follows this format:

YYYY-MM-DDTHH:MM:SS [LEVEL] message

Examples:

2025-06-01T14:22:01 [INFO] Session: wayland
2025-06-01T14:22:01 [INFO] Compositor: hyprland
2025-06-01T14:22:01 [INFO] Default browser: firefox
2025-06-01T14:22:01 [INFO] Available browsers: firefox, brave, chromium
2025-06-01T14:22:08 [DEBUG] LAUNCH: YouTube via Firefox (Native)
2025-06-01T14:22:08 [DEBUG] WRAPPER: /home/user/.pwa_manager/scripts/pwa-launch-youtube.sh

Log Levels Used

  • DEBUG — launch commands, wrapper paths, update check results, security-path validation events
  • INFO — session type, compositor, browser scan results, successful backups, pruned backup notices
  • WARNING — config load failures, failed file-log handler attachment, skipped extension URLs that failed the allowlist check
  • ERROR — missing flatpak_id, unsupported browser, failed profile config saves, unsafe tar members rejected during restore

Live Log Tail

You can watch the log in real time in a terminal while using Appify:

tail -f ~/.pwa_manager/launch.log

This is the fastest way to diagnose launch failures or silent errors.

STDERR Output

In addition to the log file, all log output is also written to stderr. If you launch Appify from a terminal, you will see log lines appear there in real time as well.

Debugging

System Info Banner

When Appify starts, a system info banner is shown at the top of the main window. It displays:

  • Display server (X11, WAYLAND, Wayland/Hyprland, etc.)
  • Number of browsers detected
  • Current default browser

The window title also shows the session and compositor, for example: "Appify 2.1.0 • WAYLAND/Hyprland"

This is the quickest sanity check that Appify has correctly detected your environment.

About Dialogue

The About dialogue (hamburger menu → About) shows the full list of currently detected and installed browsers, your session type, and your default browser. This is useful for verifying that your browser was found correctly, especially for Flatpak or Snap installs.

Rescan Browsers

If you install a new browser while Appify is running, use: Hamburger menu → Rescan Browsers

This forces Appify to re-detect all native, Flatpak, and Snap browsers and updates the browser dropdown immediately.

Installed App Indicator

In the app list dropdown, apps that are already installed as desktop entries show a checkmark prefix:

  • ✓ YouTube

Apps without the checkmark have not been installed yet. If you expect an app to show ✓ but it does not, check whether the .desktop file exists at:

~/.local/share/applications/pwa-<slug>-manager.desktop

Checking Wrapper Scripts

Every installed PWA has a generated launch script at:

~/.pwa_manager/scripts/pwa-launch-<app-slug>.sh

Opening this file in a text editor shows the exact command being run, including all browser flags, profile paths, Wayland/X11 flags, and nice/ionice values. Running it directly in a terminal is the best way to reproduce a launch failure and capture the browser's own error output:

bash ~/.pwa_manager/scripts/pwa-launch-youtube.sh

Profile Directory

Each PWA has its own isolated browser profile stored at:

~/.pwa_manager/profiles/<app-slug>/

Inside you will find:

  • profile.json — stores the browser key, gamepad flag, browser type
  • installed.marker — marks this profile as installed
  • Browser data — cookies, prefs, extensions, etc.

If an app fails to launch or behaves oddly, deleting just the browser data files (or the whole profiles/<slug>/ directory) and reinstalling can often fix the issue.

How to Debug Issues

  • App won't launch
    → Check ~/.pwa_manager/launch.log for a [ERROR] or [WARNING] line.
    → Run the wrapper script directly in a terminal (see above).
    → Make sure the browser is still installed: try Rescan Browsers.

  • Browser not appearing in the dropdown
    → The browser may be installed in a location that Appify doesn't check.
    → Try running Appify from a terminal and check stderr for scan output.
    → Use Rescan Browsers after installing the browser.

  • Wayland app opens on the wrong display or crashes
    → Check that the correct compositor is shown in the title bar.
    → Check the wrapper script — the --ozone-platform and --enable-features flags should match your compositor.

  • Firefox PWA opens in an existing window instead of its own
    → The Firefox profile may not have been initialized correctly. Uninstall and reinstall the app in Appify to regenerate the profile with the correct user.js isolation settings.

  • Config errors on startup
    → If config.json is corrupt, Appify falls back to defaults and logs a WARNING. Back up and delete ~/.pwa_manager/config.json to reset.

Backing Up & Restoring Profiles

Appify 2.1.0 includes a full profile backup system accessible both from the main window and the hamburger menu.

What Gets Backed Up

A backup archive is a .tar.gz file that contains:

  • The entire browser profile directory (cookies, logins, preferences, installed extensions, local storage, etc.)
  • The app's profile.json config file
  • The launcher wrapper script (.sh)
  • The .desktop file
  • The app icon (.png)
  • A meta.json sidecar with the app's metadata

Backup Storage Location

~/.pwa_manager/.backup/<app-slug>/

Each app gets its own sub-folder. Archive filenames are timestamped:

<slug>_backup_YYYYMMDD_HHMMSS.tar.gz

Example:

~/.pwa_manager/.backup/youtube/youtube_backup_20250601_142208.tar.gz

Maximum Backups Per App

Appify keeps a maximum of 10 backups per app. Once you create an 11th backup, the oldest archive is automatically deleted. A notice is written in the log:

[INFO] Pruned old backup: youtube_backup_20250530_091532.tar.gz

How to Create a Backup

Method 1 — Quick backup button:

  1. Select an installed app from the dropdown.
  2. Click the "Backup" button in the main button row.
  3. The status bar will confirm: "Backup created: "

Method 2 — Backup Manager:

  1. Select an installed app from the dropdown.
  2. Open the hamburger menu → Backup Manager.
  3. Click "Backup Now" inside the Backup Manager dialogue.

How to Restore a Backup

  1. Select the app from the dropdown.
  2. Open the hamburger menu → Backup Manager.
  3. A list of available backups is shown, sorted newest-first, with date, time, and file size for each entry.
  4. Click "Restore" next to the backup you want to roll back to.
  5. Appify will wipe the current profile, extract the archive, and regenerate the launcher and desktop file.
  6. The status bar will confirm: "Restored from "

Security note: Appify validates every file path inside the archive before extracting anything. Archives containing absolute paths, path-traversal sequences (../../), or device files are rejected with an error.

How to Delete a Backup

  1. Open the hamburger menu → Backup Manager.
  2. Click "Delete" next to any backup you want to remove.
  3. The backup file is permanently deleted.

Manual Access

Because backups are standard .tar.gz archives, you can also extract them manually with any archive tool:

tar -xzf youtube_backup_20250601_142208.tar.gz

Reporting Issues on Discord

If you run into a bug, unexpected behaviour, or a crash, the fastest way to get help is to join the Discord server and post in the appropriate channel.

Discord Invite: https://discord.gg/7fEt5W7DPh

Before You Post

Gathering the right information before you post will help the issue get resolved much faster. Please collect the following:

  1. Appify Version
    Shown in the window title: "Appify 2.1.0 ..."

  2. Session & Compositor
    Also shown in the title bar, e.g. "WAYLAND/Hyprland" or "X11".

  3. Browser & Install Type
    Which browser were you using? Was it native, Flatpak, or Snap? (Check the About dialogue, hamburger menu → About.)

  4. The Log File
    Copy the relevant section from:
    ~/.pwa_manager/launch.log
    For a launch failure, look for lines near the timestamp when it happened. For a startup issue, copy from the beginning of the most recent session (the first [INFO] Session: line).
    You can view it with:

    cat ~/.pwa_manager/launch.log

    or

    tail -100 ~/.pwa_manager/launch.log

  5. The Wrapper Script (for launch failures)
    If an app fails to launch, attach the contents of:
    ~/.pwa_manager/scripts/pwa-launch-<app-slug>.sh

  6. Steps to Reproduce
    Describe exactly what you did, step by step, so the issue can be reproduced.

  7. What You Expected vs What Happened
    A short description of the expected outcome and the actual outcome.

How to Post on Discord

  1. Join the server at https://discord.gg/7fEt5W7DPh
  2. Go to the appropriate channel (e.g., #bug-reports or #support).
  3. Write a short summary of the issue as your message.
  4. Paste the log output inside a code block by wrapping it with triple backticks: 
    2025-06-01T14:22:08 [ERROR] Browser Firefox not found
...
  5. If the log is very long, upload it as a .txt file attachment instead of pasting it directly.

Security Vulnerabilities

If you discover a security issue, please do NOT post it publicly. Report it privately via:

Include the type of issue, which file is affected, steps to reproduce, and a proof-of-concept if you have one. Credit will be given in the project's contributors list.

© 2025 BobbyComet — Appify is licensed under GPL-3.0
GitHub: https://github.com/bobbycomet/Appify

Clone this wiki locally