Docker Restarting: KARAF_ETC is not valid: /openhab/userdata/etc

It did piss me off that I got almost always error messages when I tried to set up a new docker based openHAB installation - and I haven’t found a real solution for that in this forum. So I did run a few tests to find out what I did almost always wrong and very seldom right.

After having initialized a new openHAB container I run docker-compose ps a few times to see if my container is ‘UP’ - the first indicator that something is wrong is when I get ‘RESTARTING’ instead…
After that I run docker logs <container name> and see two possible error messages - either:

KARAF_ETC is not valid: /openhab/userdata/etc


Launching the openHAB runtime...
Error occurred shutting down framework: java.lang.NumberFormatException: null
java.lang.NumberFormatException: null
        at java.lang.Integer.parseInt(
        at java.lang.Integer.parseInt(
        at org.apache.karaf.main.ConfigProperties.<init>(
        at org.apache.karaf.main.Main.updateInstancePidAfterShutdown(
        at org.apache.karaf.main.Main.main(

In the end I found out that I need to:

  • create the conf, addons & userdata folders before the first start of the container
  • but I have to keep them empty before first start of the container
  • have to set these folders in the container configuration
  • have to set ownership for a user of my choice to the parent folder and all contained files & folders (sudo chown -R /opt/openhab)
  • have to set the UID & GID parameters for the container to the user I did choose before
  • can copy my existing configuration into the conf folder after the first successful start of the container (remember to set ownership)

On a sidenote I found out that I cause error one if I have not precreated the conf, addons & userdata folder and error two if I precreate the folder /userdata/etc/

And for the interested ones - these where my tests:

  1. ~/test1: no precreated folders, no chown / chmod, u/gid set to 1000 (main user) :x:
  2. ~/test2: no precreated folders, chown -R 1000:1000, u/gid set to 1000 :x:
  3. ~/test3: no precreated folders, chown -R 9001:9001, u/gid set to 1000 (9001 being the default uid if no uid is set for the openHAB image) :x:
    b. stop - create userdata/etc/ - start again :x:
  4. ~/test4: no precreated folders, chown -R 9001:9001, u/gid set to 9001 :x:
    b. stop - create userdata/etc/ - start again :x:
  5. ~/test5: no precreated folders, chmod -R 777, u/gid set to 1000 :x:
    b. remove container - create userdata/etc/ - start again :x:
  6. ~/test6: no precreated folders, chmod -R 777, chown -R 9001:9001, u/gid set to 9001 :x:
    b. remove container - create userdata/etc/ - start again :x:
  7. /opt/openhab7: create user openhab7, precreated folders, chown -R openhab7:openhab7, u/gid set to openhab7’s :white_check_mark:
  8. ~/test8: precreated folders (./conf, …), chown -R openhab7:openhab7, u/gid set to openhab7’s :white_check_mark:
  9. ~/test9: precreated folders in subfolder (./openhab/conf, ./openhab/addons, …), chown -R openhab7:openhab7, u/gid set to openhab7’s :white_check_mark:
  10. ~/test10: precreated folders in subfolder, no chown / chmod, u/gid set to 1000 :white_check_mark:

EDIT: error fixes
I’m just setting up openHAB via docker on a new server - and somehow my 10. test case doesn’t work anymore for me (did not go through the work of testing them all again). What did work was the following:

  • situation as described in tc 10
  • starting the docker container
  • getting the now well known error KARAF_ETC is not valid: /openhab/userdata/etc when running docker logs openhab
  • stopping the container (just stopping the container, not deleting said container)
  • deleting the folder and subfolders for the openhab container (just the folder for the openhab container, not the root folder holding my docker-compose.yml)
  • starting the container again
1 Like

I have not tried OH with Docker but if this is a working guide for set up then maybe move it to the tutorials category and throw in any other relevant info for Docker noobs. :grinning:

That sound similar to the official documentation. Perhaps the developers DO know what they are doing.

@Bruce_Osborne: You are right - the official guide states that you should create these folders, but:

  1. the guide doesn’t state that it is mandatory to create these folders - other docker images create the folders themself if you mention them in the container configuration
  2. the guide doesn’t mention that you should not copy your existing configuration into the conf folder before the first start of the container
  3. the error messages don’t point you at the problem at all

In my eyes that behavior is a derivation from the standard docker image behavior (in my limited experience) and the derivation is not mentioned in the documentation.
It seems like that is a bug and not intentional behavior - lets see what the developers think about it:

Most of us here have learned it is usually mandatory to follow the instructions. Optional instructions are usually specified as such.

I would think this behavior is a bug (I opened an issue on GitHub), if the developers of the image agree, it should be fixed and this workaround shouldn’t be necessary anymore.

1 Like

That did make the error so frustrating - the first time I did set up a docker based openHAB installation I followed the guide step for step and was successful.
When I got a bit more experienced and did some changes to my setup I did run into these troubles most of the time but not always…

1 Like

I am close to running out of various (nice) ways to tell people to RTFM :rofl:


Generally I agree - but when you followed the manual and than try to evolve your setup this bug / not documented ‘feature’ can be really annoying :sweat_smile:

1 Like

While it is a valid argument that one should follow directions on the openhab website, I chose to follow the directions on the actual docker openhab website instead. I thought that the docker would be specific for the container, while the openhab website could be awaiting change. Nowhere on the docker website does it mention creating folders.

In either case, I want to say thank you to Felix for all his very informative help, but in the end it did not work. I have, and continue to think that I now have a corrupted basic install of the foundation OpenMediaVault because of my earlier screw up trying to upgrade openhab.

I am about to format my OMV drive and reload the whole thing. I’ll let you know if the reload works.

Likely that should point to the official docs. Perhaps create an issue on GitHub for the OH distro?

This is extremely aggravating! I have completely reloaded my server with Openmediavault (it is updated and running smoother so that is a plus) and my first new Docker is supposed to be Openhab.

I created the three folders as instructed in the /opt directory (see pic).opt folder

I have my openhab user created (see pic).

I am loading into Docker_Openhab (see pic)

This is what I end up with before I get the dreaded KARAF_ETC failure (see pic)

I just noticed that the dates/times for the created folders are wrong. What’s up with that? Is there any help here for my problem?

I have both created and not created the three prime folders within the target folder (third pic) and neither worked.

What is the date/time in the container?

Have you also set ownership recursively to your openhab-user (chown -R openhab:openhab Docker_Openhab) and set the uid & gid for the openhab container to that of your openhab user?

I dont understand, I cant create the container because it keeps restarting. Let me clarify, OMV has it’s own interface for creating containers

I had portainer loaded but I don’t know how to use that to create a container, just manage already running containers.

Hi Felix, and thanks again for your perseverance, I appreciate both your and Bruce’s help. Now I am not sure. I have performed the chown operation as described, however I am unaware of “set the uid & gid for the openhab container”. Isn’t that the same as chown?

You have to set the parameters for uid & gid (as described in the openHAB Docker documentation):

  -e USER_ID=<uid_of_openhab> \
  -e GROUP_ID=<gid_of_openhab> \

Probably in the section ‚Environment Variables‘? These ID‘s have to be the same as the uid & gid of your openhab user. Under Linux you use the command id openhab to get these values - I don’t know how it works in your application :thinking:

I see in your screenshot that you have set the uid to 9001 - that’s only correct if your openhab user has this uid…

Sorry didnt understand. Yes, both are set to 9001 per the image above (you can only see one, but the other is there)

Yes, but is that the uid/gid of the openhab-user you created? According to this post you might have to install a plugin to run a shell to run the command I mentioned above :thinking: