Troubleshooting FAQ

Changes not showing up?

Were the changes in the .env, config files, or route files? 404 or 405 errors on recently added pages?

Try using php artisan optimize. If the site stops work at all, run it a second time.

Were the changes in css or images?

Try hard-refreshing your page (cmd + r for mac, ctrl + r for windows) or clearing your browser cache to see if they show up.

Initial Setup Common Issues

Root composer.json requires php ^7.4 but your php version (8.1.6) does not satisfy that requirement

You probably downloaded the wrong version of XAMPP!

Go to XAMPP's Downloads page and make sure you grab the version that matches the php version in your composer.json.

error: git upload-pack: git-pack-objects died with error.

Run these in PuTTY: git config --global pack.windowMemory "100m"
git config --global pack.packSizeLimit "100m"
git config --global pack.threads "1"

Extension Installation Common Issues

extension_tracker.php: syntax error, unexpected ';', expecting ']'

Because of the way github will do the conflicts in this file, it's really common to accidentally drop closing brackets and commas. You'll want to double check that every [ has a ],.

Ways to Troubleshoot on Local

Use the dd function

You should never use this on your server as it can easily expose information to your users, but it can be an invaluable way to see what data is being passed around when debugging an issue. When you place dd($variableName); somewhere in the code, when that line gets hit, it outputs the contents of whatever you passed to it out to your screen and completely stops all other code execution.

This is helpful in two main ways: 1. Seeing what data is being passed around - often bugs arise because of very specific data situations so being able to get an insight into what data is causing the issue can go a long way. 2. Stopping code execution can help locate what line is throwing an error - if the dd function never outputs before you get an error on screen, that means the line causing issues came before the line where you put the dd. You can keep moving the output line around until you're able to identify exactly which line caused you problems.

500 Errors - How to find and read your logs

500 errors are some of the most common errors you'll encounter on your site. If you are in your production server, they'll show up with very little information to inform you what has happened.

There are two main ways to get more information

1. Re-produce the error on your local environment, which should have error verbosity turned on. (Don't have a local? Go make one)
2. Find the error in your log files

Finding the error in your log files can be a little confusing if you've never done it before, so we'll walk through that here.

1. Navigate in your file manager to /storage/logs/ from your root LK folder
2. Find the file named with today's date
3. Open the file and scroll all the way to the bottom

At that point you should see a bunch of lines that look something like this ([...] added to represent bits that were removed for brevity):

#47 /[...]/laravel/framework/[...]/Pipeline.php(167): [...]\\PreventRequestsDuringMaintenance->handle(Object(Illuminate\\Http\\Request), Object(Closure))
#48 /[...]/laravel/framework/[...]/Pipeline.php(103): [...]\\Pipeline->Illuminate\\Pipeline\\{closure}(Object(Illuminate\\Http\\Request))
#49 /[...]/laravel/framework[...]/Kernel.php(141): [...]\\Pipeline->then(Object(Closure))

Notice the lines are numbered! What you'll want to do is carefully scroll up until you see those numbers count down to #0. We don't want to go past this set of lines and into the next error up, so it's important to not scroll through them too quickly or it'll be easy to miss.

When you get to #0 it'll look like this:

[stacktrace]
#0 [...]

And will have one additional line above that. That's your error message. It'll have a timestamp in front of it, and that's what you'll want to pay attention to, to try to solve the error, or copy into the discord so that others can help you parse what it means.

How to Read a 500 error

Most 500 errors will give you two important pieces of information - a variable name, and a file name.

An example of a 500 error:

Trying to get property 'name' of non-object (View: \site\resources\views\[...]\create_edit_submission.blade.php)

create_edit_submission.blade.php is the file where something is going wrong, and name is the variable, or function where things aren't working as expected.

While it's good to then go double check that template file to see if anything looks out of the norm, often template errors are occurring because of an issue deeper in the code. Tutorial: Adding Fields to Users/Characters/Etc has a great explanation about how the different parts of Lorekeeper hand-off to each other to explain how you can start to trace issues from a template to their cause.

Common Sources of 500 Errors

Deleted Entities

Whether it's a character, item, currency, or any other 'entity' in Lorekeeper, it's rare to delete one, and doing so can cause issues in parts of the application that don't have robust checks against something not existing. This is especially true when you start adding extensions to the mix. If you've deleted something recently and it's remotely related to the page giving you a 500 error, it's a good bet that it's the cause. If you're not sure how to fix it, then it's a good candidate for asking about in the discord server, as it can be very case by case!

Types of LK Errors

Trying to get property 'name' of non-object

This means that the code is trying to use a variable or function with the quoted name like object->name or object->name() but 'object' isn't an object type. That means it could have a string (text) content, or more often is set to null. Solving this issue generally involves figuring out why the wrong thing has been stored as 'object'.

Undefined Offset: 1

This means that the code is trying to access an array with a specific accessor string like array[$variable] where variable would contain the offset listed in the error or like array['1'] where the code is very deliberately accessing a specific value. In either case it means that that value name does not exist in the array, and debugging this error requires figuring out why something didn't get populated that likely should have been.

syntax error, unexpected 'endif', expecting end of file

This means that the code hit an extra @endif somewhere that's duplicated and likely just needs to be removed.

syntax error, unexpected end of file, expecting 'endif'

This means that the code hit the end of your blade file without reaching an @endif for one of your @ifs. Go through the listed template file and make sure every @if has it's own @endif. This can get confusing, as they can be nested several layers deep. The same thing goes for other versions of this file, so it could be {} or [] or <?php ?> that's been mismatched as well. VSCode can help with those latter ones, because it will color code the matching braces, so you can often quickly identify when a brace has changed to a color you're not expecting.

Class "App\Http\Controllers\Auth" not found

This error and similar errors, are often caused by bad merges where the initial use App\Http\Controllers\Auth or use Auth wasn't added to the top of the file. Generally it's safe to go ahead and add the class the file is missing at the top of the file with the others to fix this issue.

foreach() argument must be of type array|object, null given

Similar to some of the above errors, this one also means that information is missing that should have existed. Somewhere in the code that ran, there was a foreach($variables as $variable) and for some reason, $variables was null instead of having an array or object in it.

Undefined variable $variable

The running code is trying to use $variable but it doesn't exist in the current function. This usually occurs due to a bad merge and means that you have missing code.

syntax error, unexpected single-quoted string

This usually means you're missing a comma at the end of the line above it.

Image source not readable

There are a myriad of issues that can go wrong with images, and cause this error message, or other similar messages.

The first thing you want to check is the size of the image you are using - out of the box Lorekeeper has some pretty low limitations on image size, so you'll want to size it down at most 300dpi, less than 4MB and less than about 5kpx on the longest side. There are ways to increase this limit by changing your php limitations in the php.ini if you care to look into it.

If it's not the size of the image then it's worth bringing to the discord to ask about, and there is some useful information to figure out for us before you do:

1. Does it generate and save the image to your image folder? (public/images/characters)
2. Does it generate and save the thumbnail to your image folder?
3. Are you using a watermark? Have you customized the default watermarking at all?

Git Issues

git pull: You have divergent branches and need to specify how to reconcile them.

Don't run the commands that git lists here. It's warning message isn't helpful.

What's happening instead is that when git tries to do a pull, it does two steps. It starts with git fetch and then it tries to intelligently decide whether it should do a git merge or what git calls a "fast-forward" as the second step of the pull. (It's ok if you don't fully understand what those mean.)

The important part is that if git can't figure out which it should do on its own it gives you this warning.

Unless you're doing something really unusual you're probably either pulling in updates from the core lorekeeper, or an extension. In this case we already know we want to do a git merge. So instead of the usual pull command you'll want to click the "terminal" button in source tree (or if you're already in command line then no need), and run git merge reponame/extension/branchname and then you should be able to carry on as you would have before.

Server isn't getting updates pushed through git

There are a few things that can cause this so ultimately you should bring it up in the discord server for help but you can also do a few things to get more information about where exactly things are going wrong.

In Putty

Either have off the top of your head or find in source tree the most recent git commit message you've made.

1. cd ~/sitename.com/site_hub.git
2. git log main -1
3. If the commit message does match, continue
4. cd ~/sitename.com/www
5. git log -1
6. Wherever you identified the commit doesn't match run: git status

If you bring the information for where the commit message doesn't match and what the output of git status is to the server that will go a long way.

Reasons this occurs

There are a couple of common reasons why this may occur, that can help in debugging

1. If git status shows files that would cause conflicts - these could be blocking the hooks from running and will need to be dealt with
2. If git status doesn't show anything concerning, and git pull hub main gets your updates, then your hooks are likely broken. They could be mis-typed or you may not have set appropriate permissions on them.
3. If site_hub.git is the one that doesn't match, or git pull hub main doesn't get you any updates, there could be a mis-match in branch names in one of the repos

fatal: protocol error: bad line length character

There are two main causes of this error, that I would check in order:

1. Your ssh key authentication is no longer working correctly for some reason - stepping back through some of the steps for loading it up / putting it on the server is a good first step towards trying to fix it.
2. You recently updated sourcetree - downgrade to a prior version. I've successfully been able to use 3.4.13, but 3.4.7 has been very reliable. From here: https://www.sourcetreeapp.com/download-archives