Troubleshooting
manual
manual zettelstore
zmk
00001000000000 00001003000000 00001017000000
00001000000000 00001003000000 00001017000000
1
(c) 2020-present by Detlef Stern <ds@zettelstore.de>
20211027105921
00000000000004 00001004010000 00001004011400 00001004020000 00001004051100 00001004100000 00001004101000 00001007031200 00001008000000 00001010040100 00001010040200 00001010090100 00001012080500 00001014000000
en
EUPL-1.2-or-later
20241212153148
20241212153148
public
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 allow 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, an 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 to 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 contain 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.
Search for specific content
Problem: If you are searching for zettel with zettel content EUPL, the zettel with Zettelstore's License is not shown, but it does contain the character sequence EUPL.
Solution: The content of zettel with a zettel identifier less or equal 00009999999999 is not searched. These zettel are predefined zettel, sometimes computed zettel, with some content not related to your research. For these zettel, only the metadata can be searched.