Troubleshooting

This page lists some problems and their solutions that may occur when using your Zettelstore.

Installation

• Problem: When you double-click on the Zettelstore executable icon, macOS complains that Zettelstore is an application from an unknown developer. Therefore, it will not start Zettelstore.

  • Solution: Press the Ctrl key while opening the context menu of the Zettelstore executable with a right-click. A dialog is then opened where you can acknowledge that you understand the possible risks when you start Zettelstore. This dialog is only resented once for a given Zettelstore executable.

• Problem: When you double-click on the Zettelstore executable icon, Windows complains that Zettelstore is an application from an unknown developer.

  • Solution: Windows displays a dialog where you can acknowledge possible risks and allows to start Zettelstore.

Authentication

• Problem: Authentication is enabled for a local running Zettelstore and there is a valid user zettel for the owner. But entering user name and password at the web user interface seems to be ignored, while entering a wrong password will result in an error message.

  • Explanation: A local running Zettelstore typically means, that you are accessing the Zettelstore using an URL with schema http://, and not https://, for example http://localhost:23123. The difference between these two is the missing encryption of user name / password and for the answer of the Zettelstore if you use the http:// schema. To be secure by default, the Zettelstore will not work in an insecure environment.
  • Solution 1: If you are sure that your communication medium is safe, even if you use the http:// schema (for example, you are running the Zettelstore on the same computer you are working on, or if the Zettelstore is running on a computer in your protected local network), then you could add the entry insecure-cookie: true in you startup configuration file.
  • Solution 2: If you are not sure about the security of your communication medium (for example, if unknown persons might use your local network), then you should run an external server in front of your Zettelstore to enable the use of the https:// schema.

Working with Zettel Files

• Problem: When you delete a zettel file by removing it from the “disk”, e.g. by dropping it into the trash folder, by dragging into another folder, or by removing it from the command line, Zettelstore sometimes did not detect that change. If you access the zettel via Zettelstore, a fatal error is reported.

  • Explanation: Sometimes, the operating system does not tell Zettelstore about the removed zettel. This occurs mostly under MacOS.
  • Solution 1: If you are running Zettelstore in “simple-mode” or if you have enabled expert-mode, you are allowed to refresh the internal data by selecting “Refresh” in the Web User Interface (you find it in the menu “Lists”).
  • Solution 2: There is an API call to make Zettelstore aware of this change.
  • Solution 3: If you have an enabled Administrator Console you can use the command refresh to make your changes visible.
  • Solution 4: You configure the zettel box as “simple”.

HTML content is not shown

• Problem: You have entered some HTML code as content for your Zettelstore, but this content is not shown on the Web User Interface.

  You may have entered a Zettel with syntax “html”, or you have used an inline-zettel block with syntax “html”, or you entered a Zettel with syntax “markdown” (or “md”) and used some HTML code fragments.

  • Explanation: Working with HTML code from unknown sources may lead so severe security problems. The HTML code may force web browsers to load more content from external server, it may contain malicious JavaScript code, it may reference to CSS artifacts that itself load from external servers and may contains malicious software. Zettelstore tries to do its best to ignore problematic HTML code, but it may fail. Either because of unknown bugs or because of yet unknown changes in the future.

    Zettelstore sets a restrictive Content Security Policy, but this depends on web browsers to implement them correctly and on users to not disable it. Zettelstore will not display any HTML code, which contains a <script>> or an <iframe> tag. But attackers may find other ways to deploy their malicious code.

    Therefore, Zettelstore disallows any HTML content as a default. If you know what you are doing, e.g. because you will never copy HTML code you do not understand, you can relax this default.

  • Solution 1: If you want zettel with syntax “html” not to be ignored, you set the startup configuration key insecure-html to the value “html”.

  • Solution 2: If you want zettel with syntax “html” not to be ignored, and want to allow HTML in Markdown, you set the startup configuration key insecure-html to the value “markdown”.

  • Solution 3: If you want zettel with syntax “html” not to be ignored, and want to allow HTML in Markdown, and want to use HTML code within Zettelmarkup, you set the startup configuration key insecure-html to the value “zettelmarkup”.