Troubleshooting

In this page

Logging

The Better Commit Policy app records its internal activities to a so-called log. The log helps you to understand the activity of the app when diagnosing problems.

Viewing the log

The Better Commit Policy app writes its own log lines to the Jira log:

1. Find the logfile named atlassian-jira.log (see the guide by Atlassian).
2. Search for the text "com.midori" to find the lines written by Better Commit Policy.
3. If you can't see any log line written by the app, check if DEBUG logging is configured correctly, then use the corresponding app function again.

If you can't interpret the log lines you found, report it to our support. We are there to help you!

Configuring logging

When investigating a run-time problem, you may need to increase the logging level for the Better Commit Policy app. Doing so, it will write more details about what it does to the log, which helps you understand the problem.

How to enable DEBUG-level logging

To turn on DEBUG logging from the web interface without stopping Jira:

1. Login to Jira as administrator.
2. Go to Jira Administration → System → Logging and Profiling.
3. Click Configure logging level for another package under Default Loggers.
4. Enter "com.midori" to Package Name and choose "DEBUG" in Logging Level.
5. Click Add.
6. Check if this new package was correctly added to the Default Loggers list.

Now execute the app function that you think fails, then check the log for the details.

How to enable TRACE-level logging

In some rare cases, you may need to turn on TRACE logging, the most detailed logging level. For that, just follow the DEBUG-level logging guide but choose "TRACE" as logging level (instead of "DEBUG").

Warning: TRACE logging can produce a very high number of log lines. Therefore, it should be turned off as soon as possible!

Troubleshooting

This section gives you practical hints to find the root cause when facing non-trivial problems.

Diagnostic mode

Always start your investigation with executing the hook script in diagnostic mode. Diagnostic mode will detect most infrastructural problems and give you instructions how to fix those.

Verbose mode

Verbose mode is a special execution mode that reveals the interaction between the hook script and the Version Control System. This is similar to the "--verbose" mode or verbose logging in other software tools. Verbose mode is useful when the diagnostic mode didn't give you enough help, or when Midori is giving you technical support and asks you to upload the verbose mode output to the support ticket.

To get the verbose mode output, just include the hashtag #jcp_verbose in your commit message.

General problems

java.lang.StackOverflowError thrown while matching a regular expression pattern

Problem: While evaluating a policy, the commits are rejected with an Internal Server Error and the Jira log contains a stack trace like this:

2018-09-05 11:34:15.190 http-nio-8080-exec-8 ERROR guest 225x12890x4 61z4yp 0:0:0:0:0:0:0:1 /rest/commit-policy/1.0/commit-policy/3/verification [c.a.p.r.c.error.jersey.ThrowableExceptionMapper] Uncaught exception thrown by REST service: null
java.lang.StackOverflowError
  at java.util.regex.Pattern$GroupHead.match(Unknown Source)
  at java.util.regex.Pattern$Loop.match(Unknown Source)
  at java.util.regex.Pattern$GroupTail.match(Unknown Source)
  at java.util.regex.Pattern$BranchConn.match(Unknown Source)
  at java.util.regex.Pattern$CharProperty.match(Unknown Source)
  [...]

This is a well-known problem with the Java regex implementation. The root cause is that certain types of regular expressions are translated into deep recursive method calls in the Java runtime engine. With the default (rather conservative) JVM settings and long input texts (e.g. long commit messages), it might fill up the call stack, making the policy evaluation fail.

Solutions:

1. Re-write your regular expression to a more efficient form. It typically means avoiding repetitive alternative paths like (a|b)*.
2. Increase the stack size for your JVM by using the -Xss10m option.

You can read more hints and details here.

Python-related problems

'python' is not recognized as an internal or external command, operable program or batch file

Problem: Python is not installed. It is required to execute the hook scripts written in the Python language.

Solution: Install Python from this page (for Linux, Windows, Mac OS X).

No command 'python' found

See previous.

ImportError: No module named jcp_common

Problem: The file jcp_common.py is not found by the hook script.

Solution: That file should be part of the hook script package ZIP, so generate a new hook script and re-install every files.

ImportError: No module named jcp_config

Problem: The file jcp_config.py is not found by the hook script.

Solution: That file should be part of the hook script package ZIP, so generate a new hook script and re-install every files.

ImportError: No module named requests

Problem: The Python HTTP library called Requests is not found by the hook script. (This library is only used in app versions before 2.0.0.)

Solution: Login to Jira as administrator, then go to Jira Administration → Add-ons → Hooks Scripts and click the Show instructions link in item one of the Install the hook script guide. The steps, depending on your operating system, are explained there. Python is already installed if you saw this error message, just execute steps 1.2 and 1.3.

urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:590)

Problem: The hook script is configured to access Jira using the HTTPS protocol, but the SSL certificate used by Jira is invalid.

Solution: Fix the SSL certificate used by Jira.

Workaround: You can configure the hook script to ignore SSL certificate problems by setting ssl_no_verify = True in jcp_config.py. Note: this is not recommended in production as it imposes a security risk. Only use this workaround if you know what you are doing.

Windows-specific problems

International characters are broken.

Problem: Albeit the Better Commit Policy consistently uses Unicode everywhere, Windows, older Python versions and Subversion sometimes alter the non-English characters used in commit messages and filenames, or turn them to garbage characters. The altered strings may cause difficulties during policy verification, as we can't reliably check conditions against filenames, for example.

Solution: By default, this setting in jcp_config.py instructs the hook script to auto-detect the encoding from the system settings:

windows_default_encoding = None

If this can't find out the encoding reliably, you need to set that manually.

How?

1. Look up the region ("Western Europe") or the concrete language ("Russian") of your Windows system in the last column of the Python encodings table.
2. Take the codec name from the first column, and set that to the config file:

   windows_default_encoding = "cp1252"

   (Note that double quotes are required around the codec name!)
3. If there are multiple codecs for your language, then prefer the one that has an alias (2nd column) starting with "windows-". If that doesn't work, try the others, one by one.
4. After you saved the config file, you can retry a new commit immediately.

Long path- and file names are not working.

Problem: Windows may have difficulties with using files specified by long names like C:\\Program Files\\My Super Fancy Directory\\super.py.

Solution: It is a good practice to use short names everywhere, like:

svnlook_path = "C:\\Progra~1\\Visual~1\\bin\\svnlook.exe"

Hook script files are not found.

Problem: Windows (the Windows Explorer interface, to be precise) hides the file extensions by default, but Version Control Systems are typically looking for a certain extension or no extension. For example, Git wants the hook file called exactly pre-commit, not pre-commit.py.

Solution: All files names are generated just the way the Version Control System expects them. Do not change them, or if you did, generate a new hook script.

Visual Studio cannot run the client-side Git hook script.

Problem: Visual Studio completely ignores the hook script or shows the "Your git-hook, '.git/hooks/commit-msg', is not supported" error message (or similar). This problem may occur only with certain Visual Studio versions.

Solution:

1. Rename commit-msg to commit-msg.py.
2. Create a new commit-msg script file with the following content. It does nothing else, but explicitly invokes the Python executable passing the original the Python script (renamed above) and the original arguments.

   #!/bin/sh
   $PYTHONDIR/python .git/hooks/commit-msg.py $1

3. Set the $PYTHONDIR (system wide) environment variable if Visual Studio is executed as administrator.

Eclipse cannot run the client-side Git hook script.

Problem: JGit hook support on Windows is limited to Cygwin. Eclipse completely ignores the hook or shows error messages, even if Cygwin is installed.

Solution: Modify the first line of the commit-msg hook script to use an absolute path for the Python executable, like (your path may be different!):

#!C:/Users/IEUser/AppData/Local/Programs/Python/Python36-32/python.exe

Subversion-specific problems

Hook script can't find files.

Problem: Subversion runs the hooks in an empty environment (with no PATH environment variable defined), thus svnlook or python may not be found when specified only by their filenames. This can happen even if their directories are in the global PATH environment variable! (This problem typically occurs on Windows.)

Solution: Use full absolute paths everywhere. See the svnlook_path and python_path configuration variables.

Pre-commit script is not executed when using VisualSVN Server.

Problem: pre-commit.bat tries to write temporary files while being executed, but VisualSVN Server process has insufficient privileges for that, thus the hook script is silently ignored. Please note that since app version 2.0.0, the hook scripts precisely specify the directory for the temp files created, so this should not happen anymore.
Root cause: the working directory and most environment variables are not set when executing SVN hook scripts. In this specific case, VisualSVN uses its own installation directory (e.g. C:\Program Files\VisualSVN Server) as the working directory for the script, and this directory is very likely read-only.

Recommended solution: Make VisualSVN service run as local system account.

Alternative solution: Replace your pre-commit.bat's contents with this stripped-down version (please note that this might cause issues when using international characters in file names and commit messages!).

@echo off
setlocal enabledelayedexpansion
if [%1]==[] (
	python pre-commit
) else (
	python %1\hooks\pre-commit %1 %2 1>&2
)

I see "This commit updates multiple (2) branches" warnings in the log.

Problem: Most VCS'es make it impossible to modify files from multiple branches in the same commit. Unfortunately, branches are just directories for Subversion, therefore it is possible to modify files on any number of branches in one commit. Better Commit Policy writes this warning to the log when it faces this situation.

Solution: You should review your processes, as this is unlikely that you really want to do this. Important: in this situation, Better Commit Policy verifies the commit if that was created on trunk (reverting to the idea of modifying a single branch).

I see "This commit updates files on the tags [1.2.3, 2.3.4-beta]" warnings in the log.

Problem: Most VCS'es make it impossible to modify tagged files, as tags should capture a static snapshot, not some "moving state". Unfortunately, tags are just directories for Subversion, therefore it is possible to modify tagged files. Better Commit Policy writes this warning to the log when it faces this situation.

Solution: You should review your processes, as this is unlikely that you really want to do this.

I see "Pattern <foobar> must contain one capturing group" warnings in the log.

Problem: Subversion branches and tags are found by matching configurable regular expressions to the changed paths. (For example, if the file branches/my-branch/foo/bar.txt was modified, then my-branch will be found as the branch name.) If the regular expression don't contain a so-called capturing group, then the matching parts cannot be processed.

Solution: Check the regular expressions you configured for the global settings Subversion branch pattern and Subversion tag pattern. Make sure that those contain one capturing group.

Upgrade problems

I see "Outdated <YOUR_VCS_TYPE> hook script version 1.2.3 found" warnings in the log.

Problem: The version checker found that the hook script installed to that repository is out of date.

Solution:

1. If you are using Bitbucket: upgrade Better Commit Policy for Bitbucket.
2. Otherwise: upgrade the hook script.

I see "Outdated <YOUR_VCS_TYPE> hook script version 1.2.3 found" messages in my VCS client.

Problem: The version checker found that the hook script installed to that repository is out of date.

Solution:

1. If you are using Bitbucket: upgrade Better Commit Policy for Bitbucket.
2. Otherwise: upgrade the hook script.

I see "Upgrade the branch limiting pattern refs/heads/feature/*" warnings in the log.

Problem: Pre-3.0.0 app versions relied on Git branch names in the "refspec" format like refs/heads/feature/my-killer-improvement. From 3.0.0, the app deprecates the refs/heads/ prefix and uses the more intuitive name-only format feature/my-killer-improvement. Hook scripts will send the information using the new format and the server expects the new format.

We decided to take this step to be more consistent with the general Git tools' and Bitbucket experience.

Solution: If any of your commit policies is using branch limiting, then the branch limiting patterns should be reviewed to avoid unexpected behavior. If you are using wildcard characters, negation, then the pattern needs to be changed.

Here is a table that shows the most frequent patterns in GLOB syntax. In most cases, you just need to drop the refs/heads/ substring from the pattern. If your (more advanced) pattern is not listed here, the table will at least give you an idea what to do.

Legacy style (pre-3.0.0 version)	Modern style (3.0.0+ versions)
refs/heads/master	master
refs/heads/feature/*	feature/*
refs/heads/some-prefix*	some-prefix*
!(refs/heads/maintenance/*)	!(maintenance/*)
*some-text*	*some-text*
*some-suffix	*some-suffix
refs/heads/*	*

Note: we considered to do automatic migration, but this is not possible to convert the old patterns to the new style with 100% reliability.

I see "Although existing commits should be accepted without verification" warnings in the log.

Problem: This warning is logged if the Accept the commits that already exist in the repository (on another branch) without verification option is checked in the commit policy, but the hook script does not support that. Important: if it occurs, then all commits (including the existing ones) are verified for safety reasons.

Solution: If it occurs with pre-3.0.0 Git hook script versions, just upgrade to 3.0.0 or newer. If it occurs with Subversion or Mercurial, those hook script does not support this feature yet, so uncheck the option.

I see "Branch name refs/heads/master was normalized to master" warnings in the log.

Problem: As it is explained in the previous item, 3.0.0 or newer app versions use simple branch names (like master) instead of the refspec format (refs/heads/master). If some commit data sent to the server for verification still contains the old format, then the app will automatically remove the refs/heads/ prefix from that, plus write this warning to the log and continue the verification.

Solution: just upgrade the hook script in the repository idenfitied in the warning message. It will guarantee using the preferred format.

Questions?

Ask us any time.