Skip to content

Setup

How do I recover a forgotten username or password?

Stash saves login credentials in the config.yml file. You must reset both login and password if you have forgotten your password by doing the following:

  • Close your Stash process;
  • Open the config.yml file found in your Stash directory with a text editor;
  • Delete the login and password lines from the file and save;
  • Stash authentication should now be reset with no authentication credentials.

How can I connect to my server from elsewhere within my network?

Find the local IP address of your Stash Server (guides for Windows, MacOS, Linux). Then, on another device on your local network, open a browser to http://SERVER.IP.ADDRESS.HERE:9999.

See this article for ideas on accessing your stash from outside your network.

How do I serve Stash over SSL/TLS (HTTPS)?

This is typically accomplished by putting Stash behind a reverse proxy, such as Nginx or Caddy. Stash can also serve SSL directly. To use the built-in SSL:

  1. First you must generate a SSL certificate and key combo.

    openssl req -x509 -newkey rsa:4096 -sha256 -days 7300 -nodes -keyout stash.key -out stash.crt -extensions san -config <(echo "[req]"; echo distinguished_name=req; echo "[san]"; echo subjectAltName=DNS:stash.server,IP:127.0.0.1) -subj /CN=stash.server

    This command would need customizing for your environment. This link might be useful.

  2. Once you have a certificate and key file name them stash.crt and stash.key and place them in the same directory as the config.yml file, or the ~/.stash directory. Stash detects these and starts up using HTTPS rather than HTTP.

How do I serve Stash in a Subpath?

The basepath defaults to /. When running stash via a reverse proxy in a subpath, the basepath can be changed by having the reverse proxy pass X-Forwarded-Prefix (and optionally X-Forwarded-Port) headers. When detects these headers, it alters the basepath URL of the UI.

Error: config initialization error: missing the following mandatory settings: generated

  1. Find your config.yml file. Usually located at %userprofile%/.stash or $HOME/.stash.
  2. Open it and find generated: line.
  3. Replace with or add generated: absolute_path_to_your_generated_folder.
  4. Save and try to start Stash.

Stash is showing a "FFMPEG Not Found" error

If Stash is unable to find or download FFMPEG, then download and install it yourself.

The ffmpeg.exe and ffprobe.exe files should be placed in C:\Users\YourUsername\.stash on Windows. The ffmpeg and ffprobe files should be placed in ~/.stash on macOS / Linux.

I'm getting "Migration failed"

It can mean that you database got corrupted. You can verify that by running a few SQL statements. The easiest way to do so is to install a simple program called DB Browser for SQLite. Start the program and in the menu select File > Open Database... and select your Stash .sqlite database file. Then navigate to the Execute SQL tab and run: - PRAGMA integrity_check; - it should return ok. - PRAGMA foreign_key_check; - it should return nothing.

If you get something different it means there is an issue with your database. It's still possible that it can be recovered. You can ask for more help in one of the support channels.
Another option would be to try using an older backup if you have one.

My Python installation is not detected

  • Make sure your Python version is added to environment variable PATH. This is a common issue with Python installed from Microsoft Store on Windows.

    How to add Python to PATH

    A handy guide how you set a PATH on different operating systems: https://realpython.com/add-python-to-path/.

  • If you use multiple versions or have non standard configuration you can specify which version to use in Settings > System and under Applications Paths header set Python Executable Path.

How do I run multiple instances of Stash?

Running multiple instances of Stash can be done by specifying both the -c switch to denote an alternate config.yml filepath, and the --p switch to denote a unique port number.

Step-by-step Linux guide to running mutiple instances of Stash:

  1. Create a new directory for the alternate Stash configuration, referred to here as NEW_DIRECTORY_LOCATION.
  2. Choose a unique port number that does not conflict with other local Stash instances, referred to here as NEW_PORT_NUMBER.
  3. Initiate Stash to assume a fresh installation by running ./stash-linux --port NEW_PORT_NUMBER -c NEW_DIRECTORY_LOCATION/config.yml.
  4. Complete the Stash Setup Wizard.
  5. Using a text editor, manually update config.yml to use NEW_PORT_NUMBER. Find the line port: 9999 and replace with port: NEW_PORT_NUMBER.
  6. This instance of Stash can now be accessed by running ./stash-linux -c NEW_DIRECTORY_LOCATION/config.yml

Protecting against accidental exposure to the internet

Stash data is considered private, and Stash is not designed to be publicly exposed, except to trusted confidants. Stash has a built-in protection against accidentally exposing itself publicly outside of your network. If Stash receives a request from the public internet, and you do not have a password enabled, Stash will reject the request and stop handling requests to protect your privacy.

This often happens when you use the port-forwarding feature of your router or install Stash on a publicly accessible server, such as a VPS. When you do this, anybody in the world can access your Stash instance, so we enforce a password requirement. If your Stash instance has shutdown due to an insecure configuration, it will not handle requests again until you tell it that you have fixed the problem. After setting up either authentication, firewall, or removing your port forwarding rules, you can edit .stash/config/config.yml and remove the key security_tripwire_accessed_from_public_internet.

Alternative and safe methods to access your Stash

You may use several methods to safely access Stash from outside of your home network. In the most basic, you can enable authentication in Stash, and re-enable port forwarding. You can also use a VPN solution that allows you to securely access your home network, such as Tailscale, Zerotier, Wireguard, or others.

Using an external authentication provider

If you are an advanced user, and have secured your Stash instance behind an authwall provided by a reverse proxy or hosting solution, you may continue to use that. You simply have to edit .stash/config/config.yml and set dangerous_allow_public_without_auth to true. If you have already tripped the security feature, you will also have to remove the security_tripwire_accessed_from_public_internet key in order to allow Stash to serve requests.

Migrating from Windows to Unix or vice verse

Info

Migrating between filesystems with different path separators (/ and \) is currently unsupported.

Danger

Use at your own risk. If you do this, make sure backup your database before starting.

It's possible to manually migrate the folders table using SQL.

The following example query would replace \ with / and D:/ with /mnt/.

UPDATE folders SET path = REPLACE(path, '\', '/');
UPDATE folders SET path = REPLACE(path, 'D:/', '/mnt/');