Troubleshooting

General Troubleshooting

The best thing you can do when troubleshooting problems with your notification is to use the apprise object itself from the command line and add up the verbosity of the command (the more v's you specify, the more verbose it gets):

# In the below example, I am trying to figure out why my mailto:// line
# isn't working:
python apprise -vvv -t "test title" -b "test body" \
    mailto://user:[email protected]

The output can help you pinpoint what is wrong with your URL.

If the output appears cryptic, or you feel that you've exhausted all avenues, Don't be afraid to open a ticket and ask here. It greatly helps if you share the output received from your debug response. It might be just a simple tweak to your URL that is needed, otherwise we might have a good bug we need to solve.

Just be cautious as the debugging information can potentially expose personal information (such as your password and/or private access tokens) to the screen. Please remember to erase this or swap it with some random characters before posting such a thing publicly.

To Much Data and Overflow Directive

Out of the box, Apprise passes everything you give it right along to the notification source. Some sources can handle a large surplus of data; others might not deal with it as well and as a result, your notification doesn't seem to go through).

Apprise has a somewhat non-elegant way of handling this situation; but it's better than nothing. You simply need to tack on the overflow switch somewhere in your Apprise URL; for example:

• schema://path/?overflow=split
• schema://path/?overflow=truncate
• schema://path/?overflow=upstream
• schema://path/?other=options&more=settings&overflow=split

The possible overflow= options are defined as:

Variable	Description
split	This will break the message body into as many smaller chunks as it takes to ensure the full delivery of what you wanted to notify with. The smaller chunk sizes are based on the very restrictions put out by the notification service itself. For example, Twitter restricts public tweets to 280 characters. If your Apprise/Twitter URL was updated to look like this: twitter://<auth data>/?overflow=split, A message of say 1000 characters would be broken (and sent) via 4 smaller messages (280 + 280 + 280 + 160).
truncate	This just ensures that regardless of how much content you're passing along to a remote notification service, the contents will never exceed the restrictions set by the service itself. Take our Twitter example again (which restricts public tweets to 280 characters), If your Apprise/Twitter URL was updated to look like this: twitter://<auth data>/?overflow=truncate, A message of say 1000 characters would only send the first 280 characters to it. The rest would just be truncated and ignored.
upstream	Simply let the the upstream notification service handle all of the data passed to it (large or small). Apprise will not mangle/change it's content in any way. Note: This is the default configuration option used when the overflow= directive is not set.

Please note that the overflow= option isn't a perfect solution:

• It can fail for services like Telegram which can take content in the format of HTML (in addition to Markdown). If you're using HTML, then there is a very strong possibility that both the overflow=split and/or overflow=truncate option could cut your message in the middle of an un-closed HTML tag. Telegram doesn't fair to well to this and in the past (at the time of writing this wiki entry) would error and not display the data.
• It doesn't elegantly split/truncate messages the end of a word (near the message limits). It just makes a cut right at the notification services hard limit itself.
• The overflow=split can work against you. Consider a situation where you send thousands of log entries accidentally to you via an SMS notification service. Be prepared to get hundreds of text messages to re-construct all of the data you asked it to deliver! This may or may not be what you wanted to happen; in this case, perhaps overflow=truncate is a better choice. Some services might even concur extra costs on you if you exceed a certain message threshold. The point is, just be open minded when you choose to enable the split option with notification services that have very small message size limits. The good news that each supported notification service on the Apprise Wiki identifies what each hard limit is set to.

So while the overflow switch is a viable solution for most notification services; consider that it may not work perfectly for all.

Special Characters and URL Conflicts

Apprise is built around URLs. Unfortunately URLs have pre-reserved characters it uses as delimiters that help distinguish one argument/setting from another.

For example, in a URL, the &, /, and % all have extremely different meanings and if they also reside in your password or user-name, they can cause quite a troubleshooting mess as to why your notifications aren't working.

Now there is a workaround: you can replace these characters with special %XX character-set (encoded) values. These encoded characters won't cause the URL to be mis-interpreted allowing you to send notifications at will.

Below is a chart of special characters and the value you should set them:

Character	Escape Code	Description
%	%25	The percent sign itself is the starting value for defining the %XX character sets.
&	%26	The ampersand sign is how a URL knows to stop reading the current variable and move onto the next. If this existed within a password or username, it would only read 'up' to this character. You'll need to escape it if you make use of it.
(a space)	%20	While most URLs will work with the space, it's a good idea to escape it so that it can be clearly read from the URL.
/	%2F	The slash is the most commonly used delimiter that exists in a URL and helps define a path and/or location.
@	%40	The at symbol is what divides the user and/or password from hostname in a URL. if your username and/or password contains an '@' symbol, it can cause the url parser to get confused.
+	%2B	By default a addition/plus symbol (+) is interpreted as a space when specified in the URL. It must be escaped if you actually want the character to be represented as a +.
,	%2C	A comma only needs to be escaped in extremely rare circumstances where one exists at the very end of a specific URL that has been chained with others using a comma. See PR#104 for more details as to why you may need this.
:	%3A	A colon will never need to be escaped unless it is found as part of a user/pass combination. Hence in a url http://user:pass@host you can see that a colon is already used to separate the username from the password. Thus if your {user} actually has a colon in it, it can confuse the parser into treating what follows as a password (and not the remaining of your username). This is a very rare case as most systems don't allow a colon in a username field.