Previous | Contents | Index | Next

- Appendix B: Feedback and bug reporting
  - B.1 General guidelines
    - B.1.1 Sending large attachments
  - B.2 Reporting bugs
  - B.3 Reporting security vulnerabilities
  - B.4 Requesting extra features
  - B.5 Requesting features that have already been requested
  - B.6 Contributing to the code
  - B.7 Workarounds for SSH server bugs
  - B.8 Support requests
  - B.9 Web server administration
  - B.10 Asking permission for things
  - B.11 Mirroring the PuTTY web site
  - B.12 Praise and compliments
  - B.13 E-mail address

# Appendix B: Feedback and bug reporting

This is a guide to providing feedback to the PuTTY development team. It is provided as both a web page on the PuTTY site, and an appendix in the PuTTY manual.

Section B.1 gives some general guidelines for sending any kind of e-mail to the development team. Following sections give more specific guidelines for particular types of e-mail, such as bug reports and feature requests.

## B.1 General guidelines

The PuTTY development team gets a lot of mail. If you can possibly solve your own problem by reading the manual, reading the FAQ, reading the web site, asking a fellow user, or some other means, then it would make our lives much easier.

We get so much e-mail that we literally do not have time to answer it all. We regret this, but there's nothing we can do about it. So if you can possibly avoid sending mail to the PuTTY team, we recommend you do so. In particular, support requests (section B.8) are probably better sent to some public forum, or passed to a local expert if possible.

The PuTTY contact email address is a private mailing list containing four or five core developers. Don't be put off by it being a mailing list: if you need to send confidential data as part of a bug report, you can trust the people on the list to respect that confidence. Also, the archives aren't publicly available, so you shouldn't be letting yourself in for any spam by sending us mail.

Please use a meaningful subject line on your message. We get a lot of mail, and it's hard to find the message we're looking for if they all have subject lines like ‘PuTTY bug’.

### B.1.1 Sending large attachments

Since the PuTTY contact address is a mailing list, e-mails larger than 40Kb will be held for inspection by the list administrator, and will not be allowed through unless they really appear to be worth their large size.

If you are considering sending any kind of large data file to the PuTTY team, it's almost always a bad idea, or at the very least it would be better to ask us first whether we actually need the file. Alternatively, you could put the file on a web site and just send us the URL; that way, we don't have to download it unless we decide we actually need it, and only one of us needs to download it instead of it being automatically copied to all the developers.

(If the file contains confidential information, then you could encrypt it with our Secure Contact Key; see section F.1 for details. Please only use this for information that needs to be confidential.)

Some people like to send mail in MS Word format. Please don't send us bug reports, or any other mail, as a Word document. Word documents are roughly fifty times larger than writing the same report in plain text. In addition, most of the PuTTY team read their e-mail on Unix machines, so copying the file to a Windows box to run Word is very inconvenient. Not only that, but several of us don't even have a copy of Word!

Some people like to send us screen shots when demonstrating a problem. Please don't do this without checking with us first - we almost never actually need the information in the screen shot. Sending a screen shot of an error box is almost certainly unnecessary when you could just tell us in plain text what the error was. (On some versions of Windows, pressing Ctrl-C when the error box is displayed will copy the text of the message to the clipboard.) Sending a full-screen shot is occasionally useful, but it's probably still wise to check whether we need it before sending it.

If you must mail a screen shot, don't send it as a `.BMP` file. `BMP`s have no compression and they are much larger than other image formats such as PNG, TIFF and GIF. Convert the file to a properly compressed image format before sending it.

Please don't mail us executables, at all. Our mail server blocks all incoming e-mail containing executables, as a defence against the vast numbers of e-mail viruses we receive every day. If you mail us an executable, it will just bounce.

If you have made a tiny modification to the PuTTY code, please send us a ‘`git bundle`’ file, or a patch file, or a URL to a clone of our git repository, in preference to modified versions of entire source files. (Even if the source files are in a `.zip` or similar.) If you've only changed 10 lines, we'd prefer to receive a mail that's at most the size of the changes, instead of one containing multiple megabytes of data we already have.

(For more thoughts about sending patches, see section B.6.)

## B.2 Reporting bugs

If you think you have found a bug in PuTTY, your first steps should be:

- Check the Wishlist page on the PuTTY website, and see if we already know about the problem. If we do, it is almost certainly not necessary to mail us about it, unless you think you have extra information that might be helpful to us in fixing it. (Of course, if we actually need specific extra information about a particular bug, the Wishlist page will say so.)
- Check the Change Log on the PuTTY website, and see if we have already fixed the bug in the development snapshots.
- Check the FAQ on the PuTTY website (also provided as appendix A in the manual), and see if it answers your question. The FAQ lists the most common things which people think are bugs, but which aren't bugs.
- Download the latest development snapshot and see if the problem still happens with that. This really is worth doing. As a general rule we aren't very interested in bugs that appear in the release version but not in the development version, because that usually means they are bugs we have already fixed. On the other hand, if you can find a bug in the development version that doesn't appear in the release, that's likely to be a new bug we've introduced since the release and we're definitely interested in it.

If none of those options solved your problem, and you still need to report a bug to us, it is useful if you include some general information:

- Tell us what version of PuTTY you are running. To find this out, use the ‘About PuTTY’ option from the System menu. Please do not just tell us ‘I'm running the latest version’; e-mail can be delayed and it may not be obvious which version was the latest at the time you sent the message.
- PuTTY is a multi-platform application; tell us what version of what OS you are running PuTTY on. (If you're running on Unix, or Windows for Arm, tell us, or we'll assume you're running on Windows for Intel as this is overwhelmingly the case.)
- Tell us what protocol you are connecting with: SSH, Telnet, Rlogin, SUPDUP, or Raw mode, or a serial connection.
- Tell us what kind of server you are connecting to; what OS, and if possible what SSH server (if you're using SSH). You can get some of this information from the PuTTY Event Log (see section 3.1.3.1 in the manual).
- Send us the contents of the PuTTY Event Log, unless you have a specific reason not to (for example, if it contains confidential information that you think we should be able to solve your problem without needing to know).
- Try to give us as much information as you can to help us see the problem for ourselves. If possible, give us a step-by-step sequence of precise instructions for reproducing the fault.
- Don't just tell us that PuTTY ‘does the wrong thing’; tell us exactly and precisely what it did, and also tell us exactly and precisely what you think it should have done instead. Some people tell us PuTTY does the wrong thing, and it turns out that it was doing the right thing and their expectations were wrong. Help to avoid this problem by telling us exactly what you think it should have done, and exactly what it did do.
- If you think you can, you're welcome to try to fix the problem yourself. A patch to the code which fixes a bug is an excellent addition to a bug report. However, a patch is never a substitute for a good bug report; if your patch is wrong or inappropriate, and you haven't supplied us with full information about the actual bug, then we won't be able to find a better solution.
- `https://www.chiark.greenend.org.uk/~sgtatham/bugs.html` is an article on how to report bugs effectively in general. If your bug report is particularly unclear, we may ask you to go away, read this article, and then report the bug again.

It is reasonable to report bugs in PuTTY's documentation, if you think the documentation is unclear or unhelpful. But we do need to be given exact details of what you think the documentation has failed to tell you, or how you think it could be made clearer. If your problem is simply that you don't understand the documentation, we suggest asking around and seeing if someone will explain what you need to know. Then, if you think the documentation could usefully have told you that, send us a bug report and explain how you think we should change it.

## B.3 Reporting security vulnerabilities

If you've found a security vulnerability in PuTTY, you might well want to notify us using an encrypted communications channel, to avoid disclosing information about the vulnerability before a fixed release is available.

For this purpose, we provide a GPG key suitable for encryption: the Secure Contact Key. See section F.1 for details of this.

(Of course, vulnerabilities are also bugs, so please do include as much information as possible about them, the same way you would with any other bug report.)

## B.4 Requesting extra features

If you want to request a new feature in PuTTY, the very first things you should do are:

- Check the Wishlist page on the PuTTY website, and see if your feature is already on the list. If it is, it probably won't achieve very much to repeat the request. (But see section B.5 if you want to persuade us to give your particular feature higher priority.)
- Check the Wishlist and Change Log on the PuTTY website, and see if we have already added your feature in the development snapshots. If it isn't clear, download the latest development snapshot and see if the feature is present. If it is, then it will also be in the next release and there is no need to mail us at all.

If you can't find your feature in either the development snapshots or the Wishlist, then you probably do need to submit a feature request. Since the PuTTY authors are very busy, it helps if you try to do some of the work for us:

- Do as much of the design as you can. Think about ‘corner cases’; think about how your feature interacts with other existing features. Think about the user interface; if you can't come up with a simple and intuitive interface to your feature, you shouldn't be surprised if we can't either. Always imagine whether it's possible for there to be more than one, or less than one, of something you'd assumed there would be one of. (For example, if you were to want PuTTY to put an icon in the System tray rather than the Taskbar, you should think about what happens if there's more than one PuTTY active; how would the user tell which was which?)
- If you can program, it may be worth offering to write the feature yourself and send us a patch. See section B.6 for more about this.

## B.5 Requesting features that have already been requested

If a feature is already listed on the Wishlist, then it usually means we would like to add it to PuTTY at some point. However, this may not be in the near future. If there's a feature on the Wishlist which you would like to see in the near future, there are several things you can do to try to increase its priority level:

- Mail us and vote for it. (Be sure to mention that you've seen it on the Wishlist, or we might think you haven't even read the Wishlist). This probably won't have very much effect; if a huge number of people vote for something then it may make a difference, but one or two extra votes for a particular feature are unlikely to change our priority list immediately. Offering a new and compelling justification might help. Also, don't expect a reply.
- Offer us money if we do the work sooner rather than later. This sometimes works, but not always. The PuTTY team all have full-time jobs and we're doing all of this work in our free time; we may sometimes be willing to give up some more of our free time in exchange for some money, but if you try to bribe us for a big feature it's entirely possible that we simply won't have the time to spare - whether you pay us or not. (Also, we don't accept bribes to add bad features to the Wishlist, because our desire to provide high-quality software to the users comes first.)
- Offer to help us write the code. This is probably the only way to get a feature implemented quickly, if it's a big one that we don't have time to do ourselves. See the next section for more about this.

## B.6 Contributing to the code

Patches to PuTTY are welcome, if they're good quality. But we have high standards for a good patch. Here are some guidelines.

Talk to us if design changes are involved. If you're changing something fundamental about how PuTTY works, we might well not agree with the direction of the change. If you put a lot of effort into it and then we reject it, that's a waste of your own effort (apart from still being practice at programming). If you'd rather not waste that much time, checking with us before doing a lot of work can avoid it.

Read the design principles. Appendix E in the manual explains some ground rules for the PuTTY code base in general, such as not adding Windows-specific code outside the `windows` subdirectory.

Address the hard part of the problem. A lot of possible changes to PuTTY have an easy bit and a hard bit. If the patch only does the easy bit, this is not really different from a pure feature request (one without a patch at all). Before accepting a patch of that kind, we would still have to do the part that takes real work; if we already haven't found time to do that by ourselves, we're not going to suddenly find time just because you've done the easy part.

On the other hand, a patch that does the hard part and leaves the easy parts to us is another matter. (For example, if some change ought to be user-configurable, but you implement it unconditionally, leaving to us the mechanics of adding an option to turn it on and off.) In that situation – if the hard part is done well – we might be quite willing to say ‘Thank you! Don't worry about the boring bits, we can take it from here.’

Sometimes the hard part is a design question: is it better to do a thing this way, or that way? In that situation, we'd like to see arguments for why you decided to do it the way you did, considering the pros and cons of both. If you just pick one without even mentioning the decision – or if you only mention a single advantage of your choice, and don't comment on any disadvantages – it will look as if you didn't consider it properly at all. If we were happy to make the decision that way, we'd have done it already!

Please don't write your code with a large language model. In general, we are not fans of LLM coding, or LLMs in general, and we don't use them to develop PuTTY. They're environmentally disastrous; they're based on appropriating large numbers of people's work without credit, compensation or even consent, and then turning round and using the results to deprive those same people of livelihood; they're run by companies who have already demonstrated lack of ethics, so they can't be trusted to have your best interests at heart in future, or ours. Also, there is still a question of copyright in the generated code; as of 2026-08 there was an initial USA court decision on the subject, but that isn't the last word, especially since we are not solely interested in USA law. (We aren't even in the USA.)

We can't completely avoid engaging with some users of LLMs. In particular, reports of security vulnerabilies found by LLM techniques will still be accepted as vulnerabilities (assuming they're correct), and we'll fix them. We have no choice about that: if we didn't, those vulnerabilities would be exploited, sooner or later. But we'd prefer not to have LLM-generated code in PuTTY at all.

Here are some particular bad things people seem to like to do with LLMs. Some of them are possible without an LLM, as well; please don't do them in that situation either.

Don't send us 10× more autogenerated code than you could sensibly write yourself. If you weren't able to write that much code even once, how do you imagine we'll maintain it when changes are needed? Maybe you'd expect to maintain it in future by further use of LLMs – but we don't think that's a good answer, so we won't accept a patch of that kind in the first place.

We're not fans of LLMs in general, but we especially don't want to become dependent on LLMs to maintain code. (Or any other proprietary tool, either.) That is not just against our own interests: it's against the entire principle of free software, because it limits other people modifying and adapting our code as well.

If you have a plan that requires autogenerating huge piles of code via some other method like a conventional computer program, then that might be acceptable (depending on what it's doing). But in that case, the autogenerated code doesn't belong in the patch: the source code in a case like this is the smaller program that did the generation (that's what you'd modify in order to make future changes), and the build system should be set up to run it and compile the result.

Don't push lots of work on to other people, imagining you're saving work. In particular, running an LLM code generator and mailing us the results without having checked it over carefully. Someone has to check the code and make sure it's right; if you haven't done that work, then we would have to do it (if we accepted the patch at all), so you haven't saved effort, you've just pushed it on to us.

Another example is autogenerating hugely verbose writeups (e.g. in a bug report), including lots of irrelevant information as well as the important things. Again, somebody has to discard the unimportant parts. If the writer won't do it, the reader must do it when they read the text. So, again, letting an LLM generate way too much text is pushing effort on to somebody else, not saving it overall.

Don't rewrite the whole patch just because we requested a small change. Reviewing the rewritten code costs us a lot of effort, even if writing it cost you very little. Also, a rewrite risks introducing a fresh set of bugs to replace the ones found by the code review so far. After we've reviewed a patch once we'd rather not review the whole thing again, so don't make us do it if it isn't really necessary. Aim to make smaller and smaller changes until we accept the patch.

Don't expect us to be patient and helpful if you're relying on an LLM. Not everyone is a top-tier programmer. Less skilled people might still want to send us patches, and we don't want to be completely hostile to those people. If you write a patch with your own brain and fingers, and you need some help making it good enough because you lack skills or knowledge, then we're prepared to work with you, because it will improve your skills and knowledge as a side effect, and that's also a good thing. But if you're just pasting our advice into your LLM, then it's not having that side effect, and we lose the motivation to help you out.

Don't lie about using an LLM. If you have some reason why you think you absolutely need to use an LLM, then tell us so, and we'll see if we agree. Of course you could try just not telling us. But we'll definitely lose all patience with you if we find that out!

We're sorry to have to say all of this. We know it all looks very hostile and unwelcoming. We'd like to cheerily say ‘patches welcome!’, and leave it at that. But in the 2020s, unfortunately, that is not an attitude that works any more, because too many people take advantage of it.

## B.7 Workarounds for SSH server bugs

It's normal for SSH implementations to automatically enable workarounds for each other's bugs, using the software version strings that are exchanged at the start of the connection. Typically an SSH client will have a list of server version strings that it believes to have particular bugs, and auto-enable the appropriate set of workarounds when it sees one of those strings. (And servers will have a similar list of workarounds for client software they believe to be buggy.)

If you've found a bug in an SSH server, and you'd like us to add an auto-detected workaround for it, our policy is that the server implementor should fix it first.

If the server implementor has fixed it in the latest version, and can give us a complete description of the version strings that go with the bug, then we're happy to use those version strings as a trigger to automatically enable our workaround (assuming one is possible). We won't accept requests to auto-enable workarounds for an open-ended set of version strings, such as ‘any version of FooServer, including future ones not yet released’.

The aim of this policy is to encourage implementors to gradually converge on the actual standardised SSH protocol. If we enable people to continue violating the spec, by installing open-ended workarounds in PuTTY for bugs they're never going to fix, then we're contributing to an ecosystem in which everyone carries on having bugs and everyone else carries on having to work around them.

An exception: if an SSH server is no longer maintained at all (e.g. the company that produced it has gone out of business), and every version of it that was ever released has a bug, then that's one situation in which we may be prepared to add a workaround rule that matches all versions of that software. (The aim is to stop implementors from continuing to release software with the bug – and if they're not releasing it at all any more, then that's already done!)

We do recognise that sometimes it will be difficult to get the server maintainer to fix a bug, or even to answer support requests at all. Or it might take them a very long time to get round to doing anything about it. We're not completely unwilling to compromise: we're prepared to add manually enabled workarounds to PuTTY even for bugs that an implementation hasn't fixed yet. We just won't automatically enable the workaround unless the server maintainer has also done their part.

## B.8 Support requests

If you're trying to make PuTTY do something for you and it isn't working, but you're not sure whether it's a bug or not, then please consider looking for help somewhere else. This is one of the most common types of mail the PuTTY team receives, and we simply don't have time to answer all the questions. Questions of this type include:

- If you want to do something with PuTTY but have no idea where to start, and reading the manual hasn't helped, try posting to a public forum and see if someone can explain it to you.
- If you have tried to do something with PuTTY but it hasn't worked, and you aren't sure whether it's a bug in PuTTY or a bug in your SSH server or simply that you're not doing it right, then try posting to some public forum and see if someone can solve your problem. Or try doing the same thing with a different SSH client and see if it works with that. Please do not report it as a PuTTY bug unless you are really sure it is a bug in PuTTY.
- If someone else installed PuTTY for you, or you're using PuTTY on someone else's computer, try asking them for help first. They're more likely to understand how they installed it and what they expected you to use it for than we are.
- If you have successfully made a connection to your server and now need to know what to type at the server's command prompt, or other details of how to use the server-end software, talk to your server's system administrator. This is not the PuTTY team's problem. PuTTY is only a communications tool, like a telephone; if you can't speak the same language as the person at the other end of the phone, it isn't the telephone company's job to teach it to you.

If you absolutely cannot get a support question answered any other way, you can try mailing it to us, but we can't guarantee to have time to answer it.

## B.9 Web server administration

If the PuTTY web site is down (Connection Timed Out), please don't bother mailing us to tell us about it. Most of us read our e-mail on the same machines that host the web site, so if those machines are down then we will notice before we read our e-mail. So there's no point telling us our servers are down.

Of course, if the web site has some other error (Connection Refused, 404 Not Found, 403 Forbidden, or something else) then we might not have noticed and it might still be worth telling us about it.

If you want to report a problem with our web site, check that you're looking at our real web site and not a mirror. The real web site is at `https://www.chiark.greenend.org.uk/~sgtatham/putty/`; if that's not where you're reading this, then don't report the problem to us until you've checked that it's really a problem with the main site. If it's only a problem with the mirror, you should try to contact the administrator of that mirror site first, and only contact us if that doesn't solve the problem (in case we need to remove the mirror from our list).

## B.10 Asking permission for things

PuTTY is distributed under the MIT Licence (see appendix D for details). This means you can do almost anything you like with our software, our source code, and our documentation. The only things you aren't allowed to do are to remove our copyright notices or the licence text itself, or to hold us legally responsible if something goes wrong.

So if you want permission to include PuTTY on a magazine cover disk, or as part of a collection of useful software on a CD or a web site, then permission is already granted. You don't have to mail us and ask. Just go ahead and do it. We don't mind.

(If you want to distribute PuTTY alongside your own application for use with that application, or if you want to distribute PuTTY within your own organisation, then we recommend, but do not insist, that you offer your own first-line technical support, to answer questions about the interaction of PuTTY with your environment. If your users mail us directly, we won't be able to tell them anything useful about your specific setup.)

If you want to use parts of the PuTTY source code in another program, then it might be worth mailing us to talk about technical details, but if all you want is to ask permission then you don't need to bother. You already have permission.

If you just want to link to our web site, just go ahead. (It's not clear that we could stop you doing this, even if we wanted to!)

## B.11 Mirroring the PuTTY web site

If you want to set up a mirror of the PuTTY website, go ahead and set one up. Please don't bother asking us for permission before setting up a mirror. You already have permission.

If the mirror is in a country where we don't already have plenty of mirrors, we may be willing to add it to the list on our mirrors page. Read the guidelines on that page, make sure your mirror works, and email us the information listed at the bottom of the page.

Note that we do not promise to list your mirror: we get a lot of mirror notifications and yours may not happen to find its way to the top of the list.

Also note that we link to all our mirror sites using the `rel="nofollow"` attribute. Running a PuTTY mirror is not intended to be a cheap way to gain search rankings.

If you have technical questions about the process of mirroring, then you might want to mail us before setting up the mirror (see also the guidelines on the Mirrors page); but if you just want to ask for permission, you don't need to. You already have permission.

## B.12 Praise and compliments

One of the most rewarding things about maintaining free software is getting e-mails that just say ‘thanks’. We are always happy to receive e-mails of this type.

Regrettably we don't have time to answer them all in person. If you mail us a compliment and don't receive a reply, please don't think we've ignored you. We did receive it and we were happy about it; we just didn't have time to tell you so personally.

To everyone who's ever sent us praise and compliments, in the past and the future: you're welcome!

## B.13 E-mail address

The actual address to mail is `<putty@projects.tartarus.org>`.

If you want to provide feedback on this manual or on the PuTTY tools themselves, see the Feedback page.